Fix a number of top level doxygen issues.

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).

19 files changed, 73 insertions, 89 deletions

diff --git a/doc/Doxyfile b/doc/Doxyfile
index f5380da0..f9c0a5a0 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -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
-
-
diff --git a/doc/HACKING b/doc/HACKING
index b4cb1751..d67684bb 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -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
diff --git a/doc/cm3/DoxygenLayout_cm3.xml b/doc/cm3/DoxygenLayout_cm3.xml
index b4e2c740..9311b149 100644
--- a/doc/cm3/DoxygenLayout_cm3.xml
+++ b/doc/cm3/DoxygenLayout_cm3.xml
@@ -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=""/>
diff --git a/doc/efm32g/Doxyfile b/doc/efm32g/Doxyfile
index c163b891..a3a65c76 100644
--- a/doc/efm32g/Doxyfile
+++ b/doc/efm32g/Doxyfile
@@ -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
 
 
diff --git a/doc/efm32gg/Doxyfile b/doc/efm32gg/Doxyfile
index 8b063b90..1b939004 100644
--- a/doc/efm32gg/Doxyfile
+++ b/doc/efm32gg/Doxyfile
@@ -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
 
 
diff --git a/doc/efm32lg/Doxyfile b/doc/efm32lg/Doxyfile
index 30a594a6..2139da58 100644
--- a/doc/efm32lg/Doxyfile
+++ b/doc/efm32lg/Doxyfile
@@ -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
 
 
diff --git a/doc/efm32tg/Doxyfile b/doc/efm32tg/Doxyfile
index d104ff79..1610f21f 100644
--- a/doc/efm32tg/Doxyfile
+++ b/doc/efm32tg/Doxyfile
@@ -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
 
 
diff --git a/doc/lm3s/Doxyfile b/doc/lm3s/Doxyfile
index 56100e24..d7feff22 100644
--- a/doc/lm3s/Doxyfile
+++ b/doc/lm3s/Doxyfile
@@ -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
 
 
diff --git a/doc/lm4f/Doxyfile b/doc/lm4f/Doxyfile
index b0c1b6d5..284ac7ab 100644
--- a/doc/lm4f/Doxyfile
+++ b/doc/lm4f/Doxyfile
@@ -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
 
 
diff --git a/doc/lpc13xx/Doxyfile b/doc/lpc13xx/Doxyfile
index d231b1a0..d8284fc5 100644
--- a/doc/lpc13xx/Doxyfile
+++ b/doc/lpc13xx/Doxyfile
@@ -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
 
 
diff --git a/doc/lpc17xx/Doxyfile b/doc/lpc17xx/Doxyfile
index d9ee1f2d..0dba6631 100644
--- a/doc/lpc17xx/Doxyfile
+++ b/doc/lpc17xx/Doxyfile
@@ -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
 
 
diff --git a/doc/lpc43xx/Doxyfile b/doc/lpc43xx/Doxyfile
index 582d8044..fc6a3114 100644
--- a/doc/lpc43xx/Doxyfile
+++ b/doc/lpc43xx/Doxyfile
@@ -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
 
 
diff --git a/doc/stm32f0/Doxyfile b/doc/stm32f0/Doxyfile
index f890ec44..725499db 100644
--- a/doc/stm32f0/Doxyfile
+++ b/doc/stm32f0/Doxyfile
@@ -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
 
 
diff --git a/doc/stm32f1/Doxyfile b/doc/stm32f1/Doxyfile
index f3e27d4d..6a816afc 100644
--- a/doc/stm32f1/Doxyfile
+++ b/doc/stm32f1/Doxyfile
@@ -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
diff --git a/doc/stm32f2/Doxyfile b/doc/stm32f2/Doxyfile
index 085972ca..ed08e1e7 100644
--- a/doc/stm32f2/Doxyfile
+++ b/doc/stm32f2/Doxyfile
@@ -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
diff --git a/doc/stm32f3/Doxyfile b/doc/stm32f3/Doxyfile
index 4db5b2cd..afecf1be 100644
--- a/doc/stm32f3/Doxyfile
+++ b/doc/stm32f3/Doxyfile
@@ -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
diff --git a/doc/stm32f4/Doxyfile b/doc/stm32f4/Doxyfile
index 7ec24d6a..38617a19 100644
--- a/doc/stm32f4/Doxyfile
+++ b/doc/stm32f4/Doxyfile
@@ -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
diff --git a/doc/stm32l1/Doxyfile b/doc/stm32l1/Doxyfile
index c6c65674..34908e85 100644
--- a/doc/stm32l1/Doxyfile
+++ b/doc/stm32l1/Doxyfile
@@ -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
 
 
diff --git a/doc/usb/Doxyfile b/doc/usb/Doxyfile
index ff48cb33..fcd2745d 100644
--- a/doc/usb/Doxyfile
+++ b/doc/usb/Doxyfile
@@ -24,8 +24,6 @@ EXCLUDE_PATTERNS       =
 
 LAYOUT_FILE 		   = DoxygenLayout_usb.xml
 
-TAGFILES               = 
-
 GENERATE_TAGFILE       = usb.tag
 
 ENABLE_PREPROCESSING    = NO