aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMarti Bolivar <mbolivar@leaflabs.com>2012-05-10 15:47:56 -0400
committerMarti Bolivar <mbolivar@leaflabs.com>2012-05-10 15:48:48 -0400
commit6ecabd970516bb374000f9074b5a4323da2482d5 (patch)
tree1f4950e4a843a5bde030cd0b0f67f5a4e84cf9aa
parent9ebe3545cb63a0afec3958b1ddda582d32106a4a (diff)
downloadlibrambutan-6ecabd970516bb374000f9074b5a4323da2482d5.tar.gz
librambutan-6ecabd970516bb374000f9074b5a4323da2482d5.zip
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>
-rw-r--r--support/doxygen/Doxyfile4
-rwxr-xr-xsupport/doxygen/evil_mangler.awk38
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 "}"
+ }
+}