EMTime/libopencm3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix a number of top level doxygen issues.

Browse Source 
So that the navigation pane works correctly in browsers.
Some additional doc fixes put in where found (but many more still to go).
Added some dummy .c and .h files to bring the associated docs into line.
makefile changed to allow 'make html' as well as 'make doc' (the latter only does html anyway).
This commit is contained in:
Ken Sarkies
2014-01-14 22:58:48 +10:30
committed by Frantisek Burian
parent a54a12e1c9
commit 3c6e9fd56d
78 changed files with 792 additions and 304 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
doc/Doxyfile
View File

@@ -19,14 +19,3 @@ LAYOUT_FILE = DoxygenLayout.xml
GENERATE_LATEX = NO
TAGFILES = ./cm3/cm3.tag=../cm3/html \
./stm32/stm32.tag=../stm32/html \
./stm32f1/stm32f1.tag=../stm32f1/html \
./stm32f4/stm32f4.tag=../stm32f4/html \
./lm3s/lm3s.tag=../lm3s/html \
./lm4f/lm4f.tag=../lm4f/html \
./lpc13xx/lpc13xx.tag=../lpc13xx/html \
./lpc17xx/lpc17xx.tag=../lpc17xx/html \
./lpc43xx/lpc43xx.tag=../lpc43xx/html

39
doc/HACKING
View File

@@ -11,18 +11,7 @@ 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.
order.
Markup
------
@@ -50,6 +39,32 @@ 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

1
doc/cm3/DoxygenLayout_cm3.xml
View File

@@ -4,6 +4,7 @@
<tab type="mainpage" visible="yes" title="libopencm3"/>
<tab type="user" visible="yes" url="../../html/index.html" title="Back to Top" intro=""/>
<tab type="modules" visible="yes" title="CM3 Core" intro=""/>
<tab type="user" visible="yes" url="../../usb/html/modules.html" title="Generic USB" intro=""/>
<tab type="user" visible="yes" url="../../stm32f0/html/modules.html" title="STM32F0" intro=""/>
<tab type="user" visible="yes" url="../../stm32f1/html/modules.html" title="STM32F1" intro=""/>
<tab type="user" visible="yes" url="../../stm32f2/html/modules.html" title="STM32F2" intro=""/>

4
doc/efm32g/Doxyfile
View File

@@ -23,10 +23,8 @@ EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32g.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html \
GENERATE_TAGFILE = efm32g.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/efm32gg/Doxyfile
View File

@@ -23,10 +23,8 @@ EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32gg.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html \
GENERATE_TAGFILE = efm32gg.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/efm32lg/Doxyfile
View File

@@ -23,10 +23,8 @@ EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32lg.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html \
GENERATE_TAGFILE = efm32lg.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/efm32tg/Doxyfile
View File

@@ -23,10 +23,8 @@ EXCLUDE =
LAYOUT_FILE = DoxygenLayout_efm32tg.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html \
GENERATE_TAGFILE = efm32tg.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/lm3s/Doxyfile
View File

@@ -21,10 +21,8 @@ INPUT = ../../include/libopencm3/license.dox \
LAYOUT_FILE = DoxygenLayout_lm3s.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = lm3s.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/lm4f/Doxyfile
View File

@@ -21,10 +21,8 @@ INPUT = ../../include/libopencm3/license.dox \
LAYOUT_FILE = DoxygenLayout_lm4f.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = lm4f.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/lpc13xx/Doxyfile
View File

@@ -21,10 +21,8 @@ INPUT = ../../include/libopencm3/license.dox \
LAYOUT_FILE = DoxygenLayout_lpc13xx.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = lpc13xx.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/lpc17xx/Doxyfile
View File

@@ -21,10 +21,8 @@ INPUT = ../../include/libopencm3/license.dox \
LAYOUT_FILE = DoxygenLayout_lpc17xx.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = lpc17xx.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

4
doc/lpc43xx/Doxyfile
View File

@@ -21,10 +21,8 @@ INPUT = ../../include/libopencm3/license.dox \
LAYOUT_FILE = DoxygenLayout_lpc43xx.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = lpc43xx.tag
ENABLE_PREPROCESSING = NO
ENABLE_PREPROCESSING = YES

20
doc/stm32f0/Doxyfile
View File

@@ -13,26 +13,26 @@
# Local settings
#---------------------------------------------------------------------------
WARN_LOGFILE = doxygen_stm32f0.log
WARN_LOGFILE = doxygen_stm32f0.log
INPUT = ../../include/libopencm3/license.dox \
INPUT = ../../include/libopencm3/license.dox \
../../include/libopencm3/stm32/f0 \
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/f0 \
INPUT += ../../lib/stm32/f0 \
../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/f0/usb.h \
EXCLUDE = ../../include/libopencm3/stm32/f0/usb.h \
../../include/libopencm3/stm32/f0/usb_desc.h
EXCLUDE_PATTERNS = *_common_f24.h *_common_f24.c
EXCLUDE_PATTERNS = *_common_*f24.h *_common_*f24.c \
*_common_*f234.h *_common_*f234.c \
*_common_*f124.h *_common_*f124.c
LAYOUT_FILE = DoxygenLayout_stm32f0.xml
LAYOUT_FILE = DoxygenLayout_stm32f0.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = stm32f0.tag
GENERATE_TAGFILE = stm32f0.tag
ENABLE_PREPROCESSING = YES
ENABLE_PREPROCESSING = YES

7
doc/stm32f1/Doxyfile
View File

@@ -25,12 +25,13 @@ INPUT += ../../lib/stm32/f1 \
EXCLUDE = ../../include/libopencm3/stm32/f1/usb.h \
../../include/libopencm3/stm32/f1/usb_desc.h
EXCLUDE_PATTERNS = *_common_f24.h *_common_f24.c
EXCLUDE_PATTERNS = *_common_*f24.h *_common_*f24.c \
*_common_*f234.h *_common_*f234.c \
*_common_*f024.h *_common_*f024.c \
*_common_*f03.h *_common_*f03.c
LAYOUT_FILE = DoxygenLayout_stm32f1.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = stm32f1.tag
ENABLE_PREPROCESSING = YES

8
doc/stm32f2/Doxyfile
View File

@@ -22,14 +22,14 @@ INPUT = ../../include/libopencm3/license.dox \
INPUT += ../../lib/stm32/f2 \
../../lib/stm32/common
EXCLUDE =
EXCLUDE =
EXCLUDE_PATTERNS = *_common_f13.h *_common_f13.c
EXCLUDE_PATTERNS = *_common_f13.h *_common_f13.c \
*_common_*f013.h *_common_*f013.c \
*_common_*f03.h *_common_*f03.c
LAYOUT_FILE = DoxygenLayout_stm32f2.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = stm32f2.tag
ENABLE_PREPROCESSING = YES

8
doc/stm32f3/Doxyfile
View File

@@ -22,15 +22,11 @@ INPUT += ../../lib/stm32/f3 \
EXCLUDE = ../../include/libopencm3/stm32/f3/usb.h \
../../include/libopencm3/stm32/f3/usb_desc.h
EXCLUDE_PATTERNS = *_common_f24.h *_common_f24.c
EXCLUDE_PATTERNS += *_common_f124.h *_common_f124.c
EXCLUDE_PATTERNS += *_common_l1f24.h *_common_l1f24.c
EXCLUDE_PATTERNS += *_common_bcd.h *_common_bcd.c
EXCLUDE_PATTERNS = *_common_*f*24.h *_common_*f*24.c \
*_common_bcd.h *_common_bcd.c
LAYOUT_FILE = DoxygenLayout_stm32f3.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = stm32f3.tag
ENABLE_PREPROCESSING = YES

8
doc/stm32f4/Doxyfile
View File

@@ -22,14 +22,14 @@ INPUT = ../../include/libopencm3/license.dox \
INPUT += ../../lib/stm32/f4 \
../../lib/stm32/common
EXCLUDE =
EXCLUDE =
EXCLUDE_PATTERNS = *_common_f13.h *_common_f13.c
EXCLUDE_PATTERNS = *_common_f*3.h *_common_f*3.c \
*_common_*f013.h *_common_*f013.c \
*_common_*f03.h *_common_*f03.c
LAYOUT_FILE = DoxygenLayout_stm32f4.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
GENERATE_TAGFILE = stm32f4.tag
ENABLE_PREPROCESSING = YES

22
doc/stm32l1/Doxyfile
View File

@@ -7,7 +7,7 @@
# Common Include File
#---------------------------------------------------------------------------
@INCLUDE = ../Doxyfile_common
@INCLUDE = ../Doxyfile_common
#---------------------------------------------------------------------------
# Local settings
@@ -16,26 +16,28 @@
WARN_LOGFILE = doxygen_stm32l1.log
INPUT = ../../include/libopencm3/license.dox \
../../include/libopencm3/stm32/l1 \
../../include/libopencm3/stm32/common
../../include/libopencm3/stm32/l1 \
../../include/libopencm3/stm32/common
INPUT += ../../lib/stm32/l1 \
../../lib/stm32/common
../../lib/stm32/common
EXCLUDE = ../../include/libopencm3/stm32/common/gpio_common_f24.h \
../../include/libopencm3/stm32/common/timer_common_f24.h
../../include/libopencm3/stm32/common/timer_common_f24.h \
../../include/libopencm3/stm32/common/crypto_common_f24.h \
../../include/libopencm3/stm32/common/hash_common_f24.h
EXCLUDE += ../../lib/stm32/common/gpio_common_f24.c \
../../lib/stm32/common/timer_common_f24.c
../../lib/stm32/common/timer_common_f24.c \
../../lib/stm32/common/crypto_common_f24.c \
../../lib/stm32/common/hash_common_f24.c
EXCLUDE_PATTERNS =
LAYOUT_FILE = DoxygenLayout_stm32l1.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
LAYOUT_FILE = DoxygenLayout_stm32l1.xml
GENERATE_TAGFILE = stm32l1.tag
ENABLE_PREPROCESSING = YES
ENABLE_PREPROCESSING = YES

2
doc/usb/Doxyfile
View File

@@ -24,8 +24,6 @@ EXCLUDE_PATTERNS =
LAYOUT_FILE = DoxygenLayout_usb.xml
TAGFILES =
GENERATE_TAGFILE = usb.tag
ENABLE_PREPROCESSING = NO