aboutsummaryrefslogtreecommitdiff
path: root/doc/HACKING
blob: 07fb872a07f6916c4a7a2423ca66cfd4c9f9ab47 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
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. Tag files are generated and used by other doxygen runs to resolve links.

Tagfiles
--------

Tagfiles contain all information about the document, and are used to resolve
references in other documents. The groups defined in these external documents
are not shown when EXTERNAL_GROUPS = NO. The high level tagfiles must be
generated before any others so order is important.

As well as the processor families, a "cm3" subdirectory is used to generate
a tagfile to integrate the CM3 common core defines.

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 family must have a heading section
in which an @defgroup defines the group names. 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.

Common header and source files must have an @addgroup to include its
documentation into the appropriate peripheral group. These must not have any
reference to family groupings to allow them to be incorporated into multiple
family groups.

Each function must have a header with an @brief, and where appropriate
@parameter and @return elements. These must describe the allowable parameter
ranges preferably with reference to a suitable define.

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

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