diff options
Diffstat (limited to 'libopencm3/doc/HACKING')
| -rw-r--r-- | libopencm3/doc/HACKING | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/libopencm3/doc/HACKING b/libopencm3/doc/HACKING new file mode 100644 index 0000000..d67684b --- /dev/null +++ b/libopencm3/doc/HACKING @@ -0,0 +1,114 @@ +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. LaTeX and pdf files are produced +separately. Due to relative referencing used in the files, the directory +structure is important and should be maintained. + +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. + +Generation of PDF +----------------- + +The needs for pdf documents differ from HTML so separate Doxyfile_latex +files are provided. + +@INCLUDE = ../Doxyfile_common +GENERATE_LATEX = YES +GENERATE_HTML = NO + |