Changes to doxygen markup to solve a few problems that upset

doxygen, and to correct minor errors.

Author: Ken Sarkies

HACKING_COMMON_DOC

@@ -35,6 +35,20 @@ NOTE: The common source files MUST have the "dispatch" header so that
 compilation will use the specific defines for the subfamily being compiled.
 These can differ between subfamilies.
 
+NOTE: The common source files must have a line of the form
+
+#ifdef LIBOPENCM3_xxx_H
+
+where xxx is the associated peripheral name. This prevents the common files
+from being included accidentally into a user's application. This however
+causes doxygen to skip processing of the remainder of the file. Thus a
+
+@cond ... @endcond
+
+directive must be placed around the statement to prevent doxygen from
+processing it. This works only for doxygen 1.8.4 or later. At the present
+time most distros have an earlier buggy version.
+
 Documentation
 -------------
 

doc/HACKING

@@ -33,7 +33,7 @@ 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
+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.
@@ -78,6 +78,7 @@ 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
 

doc/stm32f1/Doxyfile

@@ -33,6 +33,6 @@ TAGFILES               = ../cm3/cm3.tag=../../cm3/html
 
 GENERATE_TAGFILE       = stm32f1.tag
 
-ENABLE_PREPROCESSING    = NO
+ENABLE_PREPROCESSING   = YES
 
 

doc/stm32f2/Doxyfile

@@ -32,6 +32,6 @@ TAGFILES               = ../cm3/cm3.tag=../../cm3/html
 
 GENERATE_TAGFILE       = stm32f2.tag
 
-ENABLE_PREPROCESSING    = NO
+ENABLE_PREPROCESSING    = YES
 
 

doc/stm32f4/Doxyfile

@@ -32,6 +32,6 @@ TAGFILES               = ../cm3/cm3.tag=../../cm3/html
 
 GENERATE_TAGFILE       = stm32f4.tag
 
-ENABLE_PREPROCESSING    = NO
+ENABLE_PREPROCESSING    = YES
 
 

doc/stm32l1/Doxyfile

@@ -36,6 +36,6 @@ TAGFILES               = ../cm3/cm3.tag=../../cm3/html
 
 GENERATE_TAGFILE       = stm32l1.tag
 
-ENABLE_PREPROCESSING    = NO
+ENABLE_PREPROCESSING    = YES
 
 

include/libopencm3/stm32/common/crc_common_all.h

@@ -27,7 +27,9 @@
 The order of header inclusion is important. crc.h includes the device
 specific memorymap.h header before including this header file.*/
 
+/** @cond */
 #ifdef LIBOPENCM3_CRC_H
+/** @endcond */
 #ifndef LIBOPENCM3_CRC_COMMON_ALL_H
 #define LIBOPENCM3_CRC_COMMON_ALL_H
 
@@ -94,7 +96,9 @@ END_DECLS
 /**@}*/
 
 #endif
+/** @cond */
 #else
 #warning "crc_common_all.h should not be included explicitly, only via crc.h"
 #endif
+/** @endcond */
 

include/libopencm3/stm32/common/dac_common_all.h

@@ -29,7 +29,9 @@
 The order of header inclusion is important. dac.h includes the device
 specific memorymap.h header before including this header file.*/
 
+/** @cond */
 #ifdef LIBOPENCM3_DAC_H
+/** @endcond */
 #ifndef LIBOPENCM3_DAC_COMMON_ALL_H
 #define LIBOPENCM3_DAC_COMMON_ALL_H
 
@@ -93,7 +95,7 @@ specific memorymap.h header before including this header file.*/
  */
 #define DAC_CR_MAMP2_SHIFT		24
 /** @defgroup dac_mamp2 DAC Channel 2 LFSR Mask and Triangle Wave Amplitude values
-@ingroup STM32F_dac_defines
+@ingroup dac_defines
 
 Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n)-1
 @{*/
@@ -122,7 +124,7 @@ Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n)-1
 #define DAC_CR_WAVE2_SHIFT		22
 #define DAC_CR_WAVE2_DIS		(0x3 << DAC_CR_WAVE2_SHIFT)
 /** @defgroup dac_wave2_en DAC Channel 2 Waveform Generation Enable
-@ingroup STM32F_dac_defines
+@ingroup dac_defines
 
 @li NOISE: Noise wave generation enabled
 @li TRI: Triangle wave generation enabled
@@ -153,7 +155,7 @@ Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n)-1
  */
 #define DAC_CR_TSEL2_SHIFT		19
 /** @defgroup dac_trig2_sel DAC Channel 2 Trigger Source Selection
-@ingroup STM32F_dac_defines
+@ingroup dac_defines
 
 @li T6: Timer 6 TRGO event
 @li T3: Timer 3 TRGO event
@@ -205,7 +207,7 @@ Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n)-1
  */
 #define DAC_CR_MAMP1_SHIFT		8
 /** @defgroup dac_mamp1 DAC Channel 1 LFSR Mask and Triangle Wave Amplitude values
-@ingroup STM32F_dac_defines
+@ingroup dac_defines
 
 Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n+1)-1
 @{*/
@@ -234,7 +236,7 @@ Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n+1)-1
 #define DAC_CR_WAVE1_SHIFT		6
 #define DAC_CR_WAVE1_DIS		(0x3 << DAC_CR_WAVE1_SHIFT)
 /** @defgroup dac_wave1_en DAC Channel 1 Waveform Generation Enable
-@ingroup STM32F_dac_defines
+@ingroup dac_defines
 
 @li DIS: wave generation disabled
 @li NOISE: Noise wave generation enabled
@@ -266,7 +268,7 @@ Unmask bits [(n-1)..0] of LFSR/Triangle Amplitude equal to (2**(n+1)-1
  */
 #define DAC_CR_TSEL1_SHIFT		3
 /** @defgroup dac_trig1_sel DAC Channel 1 Trigger Source Selection
-@ingroup STM32F_dac_defines
+@ingroup dac_defines
 
 @li T6: Timer 6 TRGO event
 @li T3: Timer 3 TRGO event
@@ -408,9 +410,11 @@ void dac_software_trigger(data_channel dac_channel);
 END_DECLS
 
 #endif
+/** @cond */
 #else
 #warning "dac_common_all.h should not be included explicitly, only via dac.h"
 #endif
+/** @endcond */
 
 /**@}*/
 

include/libopencm3/stm32/common/dma_common_f13.h

@@ -31,7 +31,9 @@
 The order of header inclusion is important. dma.h includes the device
 specific memorymap.h header before including this header file.*/
 
+/** @cond */
 #ifdef LIBOPENCM3_DMA_H
+/** @endcond */
 #ifndef LIBOPENCM3_DMA_COMMON_F13_H
 #define LIBOPENCM3_DMA_COMMON_F13_H
 
@@ -395,9 +397,11 @@ void dma_set_number_of_data(u32 dma, u8 channel, u16 number);
 END_DECLS
 
 #endif
+/** @cond */
 #else
 #warning "dma_common_f13.h should not be included explicitly, only via dma.h"
 #endif
+/** @endcond */
 
 /**@}*/
 

include/libopencm3/stm32/common/dma_common_f24.h

@@ -28,7 +28,9 @@
 The order of header inclusion is important. dma.h includes the device
 specific memorymap.h header before including this header file.*/
 
+/** @cond */
 #ifdef LIBOPENCM3_DMA_H
+/** @endcond */
 #ifndef LIBOPENCM3_DMA_COMMON_F24_H
 #define LIBOPENCM3_DMA_COMMON_F24_H
 
@@ -608,7 +610,9 @@ void dma_set_number_of_data(u32 dma, u8 stream, u16 number);
 END_DECLS
 /**@}*/
 #endif
+/** @cond */
 #else
 #warning "dma_common_f24.h should not be included explicitly, only via dma.h"
 #endif
+/** @endcond */