|
- libopencm3 Documentation
- 12 October 2012 (C) K Sarkies
- -----------------------------
-
- Each family and subfamily of devices has a separate directory and configuration
- files. Doxygen is run independently on each of these and the result is
- integrated under a single HTML page.
- Due to relative referencing used in the files, the directory
- structure is important and should be maintained.
- The Makefile will automatically generate the list of input files based on the
- current library makefiles, so you _must_ have run built the library itself first.
-
- Each of the subdirectories has a configuration file, a layout file and
- subdirectories for the documentation. Doxygen is intended to be run inside
- these subdirectories. The Makefile will handle this in the appropriate
- order.
-
- Markup
- ------
-
- Each family has been given a group name that will allow subgrouping of API
- functions and defines in the documentation.
-
- The header and source files for each peripheral in each family must have a
- heading section in which an @defgroup defines the group name for the particular
- peripheral. This group name will be the same across all families as each one
- is documented separately. Thus for a peripheral xxx the header will have a
- group name xxx_defines and the source file will have xxx_file. This will allow
- the group to appear separately. An @ingroup must be provided to place the group
- as a subgroup of the appropriate family grouping. Note that @file is not used.
-
- The heading section must include the version number and date and authors names
- plus a license reference. Any documentation specific to the family can be
- included here. If there are common files included then their documentation will
- appear in a separate section.
-
- Common header and source files that are included into a number of families must
- have an @addgroup to include its documentation into the appropriate peripheral
- group. These headings may include authors and any specific descriptions but the
- date and version number must be omitted as it will be included from the family
- files. There must not be any reference to family groupings as these common files
- will be incorporated into multiple family groups.
-
- The common files should not be included in an application explicitly. Also the
- doxygen preprocessor must be enabled to ensure that all macros and defines are
- included. This means that common header files need to have a section at the top
- of the file of the type (eg for gpio_common_f24.h):
-
- /** @cond */
- #ifdef LIBOPENCM3_GPIO_H
- /** @endcond */
-
- and at the end of the file:
-
- /** @cond */
- #else
- #warning "gpio_common_f24.h should not be included explicitly, only via gpio.h"
- #endif
- /** @endcond */
-
- This will stop the compiler preprocessor from including the common header file
- unless the device family header file has also been included. The doxygen
- conditional clauses are needed to stop the doxygen preprocessor seeing this
- statement and so excluding processing of the common file contents.
-
- /** @cond */
- #if defined(LIBOPENCM3_GPIO_H) || defined(LIBOPENCM3_GPIO_COMMON_F24_H)
- /** @endcond */
-
- Each helper function must have a header with an @brief, and where appropriate
- additional description, @parameter and @return elements. These latter must
- describe the allowable parameter ranges preferably with reference to a suitable
- define in the corresponding header file.
-
- The Doxyfile for a family must include input files from the header and source
- subdirectories, as well as all needed common files. The common files can be
- added separately or as an entire directory with exclusions of inappropriate
- files.
-
- Doxyfiles
- ---------
-
- Doxyfile_common holds global settings.
-
- OUTPUT_DIRECTORY blank so that the output is placed in the current directory.
- RECURSIVE = NO
- EXTERNAL_GROUPS = NO
-
- Each Doxyfile_include for a processor family has:
-
- @INCLUDE = ../Doxyfile_common
- INPUT = specific directories needed, including /include/libopencm3/cm3
- in top directory to set the top level page and GNU license.
- LAYOUT_FILE = DoxygenLayout_$processor.xml
- WARN_LOGFILE = doxygen_$processor.log
- TAGFILES = ../cm3/cm3.tag=../../cm3/html
- GENERATE_TAGFILE = $processor.tag
- PREDEFINED = list of macro definitions
-
- For the top level Doxyfile
-
- INPUT = ../include/libopencm3/docmain.dox to add in the main page text
- LAYOUT_FILE = DoxygenLayout.xml
- WARN_LOGFILE = doxygen.log
- TAGFILES = cm3/cm3.tag=../cm3/html plus all families to be included.
|