Doxygen: add the Evil Mangler.

Whenever Doxygen is running on a series header, make it run an awk
script, the Evil Mangler, that pretends the file is enclosed in an
appropriate namespace declaration for the series target.

Doxygen chokes if two structs have the same name. This is a problem
for the series headers, which commonly have data structures with the
same name.  However, if those structs are in different namespaces,
Doxygen has no problems.  We obviously can't use namespaces in C
headers, so use FILTER_PATTERNS to trick Doxygen into thinking they're
there.

Ugly, but I can't think of a better way to handle this.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

2 files changed, 41 insertions, 1 deletions

diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile
index 6dbce7d..1074403 100644
--- a/support/doxygen/Doxyfile
+++ b/support/doxygen/Doxyfile
@@ -690,7 +690,9 @@ INPUT_FILTER           =
 # info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER 
 # is applied to all files.
 
-FILTER_PATTERNS        = 
+# Trick Doxygen into thinking series headers are in separate
+# namespaces; see the Evil Mangler source for more information.
+FILTER_PATTERNS        = */libmaple/stm32*/include/series/*.h=./support/doxygen/evil_mangler.awk
 
 # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using 
 # INPUT_FILTER) will be used to filter the input files when producing source 
diff --git a/support/doxygen/evil_mangler.awk b/support/doxygen/evil_mangler.awk
new file mode 100755
index 0000000..b07da72
--- /dev/null
+++ b/support/doxygen/evil_mangler.awk
@@ -0,0 +1,38 @@
+#!/usr/bin/awk -f
+
+# libmaple's own Evil Mangler
+#
+# Input filter hack to trick Doxygen into thinking that a series
+# header is in a separate namespace. This is necessary because Doxygen
+# doesn't know how to cope with two data structures with the same name
+# in different places in the project. (We do that all the time,
+# e.g. for foo_reg_map structs.)
+#
+# E.g., an STM32F1 header gets transformed into:
+#
+# namespace stm32f1 {
+# <contents of header>
+# }
+
+BEGIN {
+    # For extracting series component from header FILENAME.
+    series_regex = "/stm32[flw][0-9]*/";
+    # Holds header FILENAME. Cargo-culted; not sure why it's necessary.
+    f = "";
+    # Holds series component.
+    series = "";
+}
+{
+    if (f != FILENAME) {
+        f = FILENAME;
+        match(f, series_regex);
+        series = substr(f, RSTART + 1, RLENGTH - 2);
+        printf("namespace %s {\n", series);
+    }
+    print;
+}
+END {
+    if (series != "") {
+        print "}"
+    }
+}