aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorKen Sarkies2013-03-07 11:14:06 +1030
committerKen Sarkies2013-03-07 11:14:06 +1030
commite2022f588492d5c117743b6b13801940f4a4b03e (patch)
tree8c70e829e69094361afa51489ef097a5e663ea6c /doc
parent31aa3b6f5a9e9afa4d1bc8661cbaef147af55f74 (diff)
Repair to documentation (most documented files)
to remove errors, duplications and inconsistencies. File lib/stm32/f1/pwr.c - all code removed as it duplicates that in common/pwr_common.c Remaining changes do not affect code. Compiles OK. TODO efm32 has no code so generates no modules TODO F2 needs pwr.c TODO L1 needs dma.h and dma.c
Diffstat (limited to 'doc')
-rw-r--r--doc/DoxygenLayout.xml10
-rw-r--r--doc/HACKING43
-rw-r--r--doc/cm3/DoxygenLayout_cm3.xml1
-rw-r--r--doc/stm32f2/Doxyfile2
-rw-r--r--doc/stm32f4/Doxyfile2
-rw-r--r--doc/stm32l1/DoxygenLayout_stm32l1.xml2
6 files changed, 35 insertions, 25 deletions
diff --git a/doc/DoxygenLayout.xml b/doc/DoxygenLayout.xml
index a602652..c1a7744 100644
--- a/doc/DoxygenLayout.xml
+++ b/doc/DoxygenLayout.xml
@@ -8,16 +8,16 @@
<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=""/>
<tab type="user" visible="yes" url="../stm32f4/html/modules.html" title="STM32F4" intro=""/>
- <tab type="user" visible="yes" url="../../stm32l1/html/modules.html" title="STM32L1" intro=""/>
+ <tab type="user" visible="yes" url="../stm32l1/html/modules.html" title="STM32L1" intro=""/>
<tab type="user" visible="yes" url="../lm3s/html/modules.html" title="LM3S" intro=""/>
<tab type="user" visible="yes" url="../lm4f/html/modules.html" title="LM4F" intro=""/>
<tab type="user" visible="yes" url="../lpc13xx/html/modules.html" title="LPC13" intro=""/>
<tab type="user" visible="yes" url="../lpc17xx/html/modules.html" title="LPC17" intro=""/>
<tab type="user" visible="yes" url="../lpc43xx/html/modules.html" title="LPC43" intro=""/>
- <tab type="user" visible="yes" url="../../emf32g/html/modules.html" title="EMF32 Gecko" intro=""/>
- <tab type="user" visible="yes" url="../../emf32gg/html/modules.html" title="EMF32 Giant Gecko" intro=""/>
- <tab type="user" visible="yes" url="../../emf32lg/html/modules.html" title="EMF32 Leopard Gecko" intro=""/>
- <tab type="user" visible="yes" url="../../emf32tg/html/modules.html" title="EMF32 Tiny Gecko" intro=""/>
+ <tab type="user" visible="yes" url="../emf32g/html/modules.html" title="EMF32 Gecko" intro=""/>
+ <tab type="user" visible="yes" url="../emf32gg/html/modules.html" title="EMF32 Giant Gecko" intro=""/>
+ <tab type="user" visible="yes" url="../emf32lg/html/modules.html" title="EMF32 Leopard Gecko" intro=""/>
+ <tab type="user" visible="yes" url="../emf32tg/html/modules.html" title="EMF32 Tiny Gecko" intro=""/>
<tab type="namespaces" visible="yes" title="">
<tab type="namespaces" visible="yes" title="" intro=""/>
<tab type="namespacemembers" visible="yes" title="" intro=""/>
diff --git a/doc/HACKING b/doc/HACKING
index 07fb872..4863676 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -28,23 +28,32 @@ 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.
+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 deparately. 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.
+
+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
diff --git a/doc/cm3/DoxygenLayout_cm3.xml b/doc/cm3/DoxygenLayout_cm3.xml
index 66ed9f3..1206a19 100644
--- a/doc/cm3/DoxygenLayout_cm3.xml
+++ b/doc/cm3/DoxygenLayout_cm3.xml
@@ -4,7 +4,6 @@
<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="../../stm32/html/modules.html" title="STM32" 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=""/>
<tab type="user" visible="yes" url="../../stm32f4/html/modules.html" title="STM32F4" intro=""/>
diff --git a/doc/stm32f2/Doxyfile b/doc/stm32f2/Doxyfile
index bc0348e..cfe5dd5 100644
--- a/doc/stm32f2/Doxyfile
+++ b/doc/stm32f2/Doxyfile
@@ -24,7 +24,7 @@ INPUT += ../../lib/stm32/f2 \
EXCLUDE =
-EXCLUDE_PATTERNS =
+EXCLUDE_PATTERNS = *_common_f13.h *_common_f13.c
LAYOUT_FILE = DoxygenLayout_stm32f2.xml
diff --git a/doc/stm32f4/Doxyfile b/doc/stm32f4/Doxyfile
index eee41e9..c5016f4 100644
--- a/doc/stm32f4/Doxyfile
+++ b/doc/stm32f4/Doxyfile
@@ -24,6 +24,8 @@ INPUT += ../../lib/stm32/f4 \
EXCLUDE =
+EXCLUDE_PATTERNS = *_common_f13.h *_common_f13.c
+
LAYOUT_FILE = DoxygenLayout_stm32f4.xml
TAGFILES = ../cm3/cm3.tag=../../cm3/html
diff --git a/doc/stm32l1/DoxygenLayout_stm32l1.xml b/doc/stm32l1/DoxygenLayout_stm32l1.xml
index 86ee511..28837e1 100644
--- a/doc/stm32l1/DoxygenLayout_stm32l1.xml
+++ b/doc/stm32l1/DoxygenLayout_stm32l1.xml
@@ -5,7 +5,7 @@
<tab type="pages" visible="yes" title="General Information" intro=""/>
<tab type="user" visible="yes" url="../../html/index.html" title="Back to Top" intro=""/>
<tab type="user" visible="yes" url="../../cm3/html/modules.html" title="CM3 Core" intro=""/>
- <tab type="user" visible="yes" url="../../stm32f1/html/modules.html" title="STM32F2" 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=""/>
<tab type="user" visible="yes" url="../../stm32f4/html/modules.html" title="STM32F4" intro=""/>
<tab type="modules" visible="yes" title="STM32L1" intro=""/>