107 lines
4.3 KiB
Plaintext
107 lines
4.3 KiB
Plaintext
|
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.
|
||
|
|
|