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.