From 6ae19973da18ae67db0f0495c6b3cdf44797e2c8 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 3 May 2012 14:04:36 -0400 Subject: Doxyfile: Allow group documentation. This change allows us to document several members of a group with one Doxygen comment. It's not clear how well this will work out in practice. Signed-off-by: Marti Bolivar --- support/doxygen/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'support/doxygen') diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile index 67b7692..35e6bd6 100644 --- a/support/doxygen/Doxyfile +++ b/support/doxygen/Doxyfile @@ -263,7 +263,7 @@ IDL_PROPERTY_SUPPORT = YES # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. -DISTRIBUTE_GROUP_DOC = NO +DISTRIBUTE_GROUP_DOC = YES # Set the SUBGROUPING tag to YES (the default) to allow class member groups of # the same type (for instance a group of public functions) to be put as a -- cgit v1.2.3 From 392d791b26de9f77170332abab57c6542a4ced79 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 9 May 2012 15:00:45 -0400 Subject: Shut up, doxygen. Signed-off-by: Marti Bolivar --- support/doxygen/Doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'support/doxygen') diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile index 35e6bd6..5a5d7ed 100644 --- a/support/doxygen/Doxyfile +++ b/support/doxygen/Doxyfile @@ -537,7 +537,7 @@ LAYOUT_FILE = # The QUIET tag can be used to turn on/off the messages that are generated # by doxygen. Possible values are YES and NO. If left blank NO is used. -QUIET = NO +QUIET = YES # The WARNINGS tag can be used to turn on/off the warning messages that are # generated by doxygen. Possible values are YES and NO. If left blank @@ -549,7 +549,7 @@ WARNINGS = YES # for undocumented members. If EXTRACT_ALL is set to YES then this flag will # automatically be disabled. -WARN_IF_UNDOCUMENTED = YES +WARN_IF_UNDOCUMENTED = NO # If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for # potential errors in the documentation, such as not documenting some -- cgit v1.2.3 From 94d95639c124ebff02a9944237ca9c1764c9cca9 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Wed, 9 May 2012 15:09:52 -0400 Subject: Change __DOXYGEN_PREDEFINED_HACK to __DOXYGEN__. avr-gcc does it this way. Seems ok to me. Signed-off-by: Marti Bolivar --- libmaple/include/libmaple/stm32.h | 7 +++---- libmaple/stm32f1/include/series/stm32.h | 4 ++-- support/doxygen/Doxyfile | 2 +- 3 files changed, 6 insertions(+), 7 deletions(-) (limited to 'support/doxygen') diff --git a/libmaple/include/libmaple/stm32.h b/libmaple/include/libmaple/stm32.h index 6b8e905..097a016 100644 --- a/libmaple/include/libmaple/stm32.h +++ b/libmaple/include/libmaple/stm32.h @@ -59,8 +59,7 @@ extern "C" { /* The series header is responsible for defining: * - * - Everything enclosed in the following __DOXYGEN_PREDEFINED_HACK - * conditional block. + * - Everything in the following __DOXYGEN__ conditional block. * * - STM32_HAVE_FSMC: 1 if the MCU has the FSMC peripheral, and 0 * otherwise. @@ -79,7 +78,7 @@ extern "C" { #error "Bad STM32F1 configuration. Check header for your MCU." #endif -#ifdef __DOXYGEN_PREDEFINED_HACK +#ifdef __DOXYGEN__ /* * Clock configuration. @@ -162,7 +161,7 @@ extern "C" { */ #define STM32_HAVE_USB -#endif /* __DOXYGEN_PREDEFINED_HACK */ +#endif /* __DOXYGEN__ */ /* * The following are for backwards compatibility only. diff --git a/libmaple/stm32f1/include/series/stm32.h b/libmaple/stm32f1/include/series/stm32.h index e6d3b19..e01c494 100644 --- a/libmaple/stm32f1/include/series/stm32.h +++ b/libmaple/stm32f1/include/series/stm32.h @@ -181,7 +181,7 @@ extern "C" { * Doxygen */ -#ifdef __DOXYGEN_PREDEFINED_HACK +#ifdef __DOXYGEN__ /** * @brief STM32 line value for the STM32F1 MCU being targeted. @@ -192,7 +192,7 @@ extern "C" { */ #define STM32_F1_LINE -#endif /* __DOXYGEN_PREDEFINED_HACK */ +#endif /* __DOXYGEN__ */ #ifdef __cplusplus } diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile index 5a5d7ed..a267c36 100644 --- a/support/doxygen/Doxyfile +++ b/support/doxygen/Doxyfile @@ -1377,7 +1377,7 @@ PREDEFINED = __attribute__()= \ STM32_MEDIUM_DENSITY \ STM32_HIGH_DENSITY \ STM32_XL_DENSITY \ - __DOXYGEN_PREDEFINED_HACK + __DOXYGEN__ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. -- cgit v1.2.3 From 8bed1f3e3a5db4268c4f9f49319d993c922fe496 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 10 May 2012 13:20:03 -0400 Subject: Doxyfile: Disable TYPEDEF_HIDES_STRUCT to work around Breathe issues. This works around a problem we're having getting the XML for the series headers into a form that we can work with in leaflabs-docs. Signed-off-by: Marti Bolivar --- support/doxygen/Doxyfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'support/doxygen') diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile index a267c36..6dbce7d 100644 --- a/support/doxygen/Doxyfile +++ b/support/doxygen/Doxyfile @@ -281,7 +281,7 @@ SUBGROUPING = YES # be useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. -TYPEDEF_HIDES_STRUCT = YES +TYPEDEF_HIDES_STRUCT = NO # The SYMBOL_CACHE_SIZE determines the size of the internal cache use to # determine which symbols to keep in memory and which to flush to disk. -- cgit v1.2.3 From 6ecabd970516bb374000f9074b5a4323da2482d5 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Thu, 10 May 2012 15:47:56 -0400 Subject: 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 --- support/doxygen/Doxyfile | 4 +++- support/doxygen/evil_mangler.awk | 38 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 1 deletion(-) create mode 100755 support/doxygen/evil_mangler.awk (limited to 'support/doxygen') 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 { +# +# } + +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 "}" + } +} -- cgit v1.2.3 From 5eda0127524f60d4e09dc8213e042915e22351f7 Mon Sep 17 00:00:00 2001 From: Marti Bolivar Date: Fri, 11 May 2012 14:49:17 -0400 Subject: Doxyfile: Add to PREDEFINED to cover libmaple_types.h. Signed-off-by: Marti Bolivar --- support/doxygen/Doxyfile | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'support/doxygen') diff --git a/support/doxygen/Doxyfile b/support/doxygen/Doxyfile index 1074403..daeaf38 100644 --- a/support/doxygen/Doxyfile +++ b/support/doxygen/Doxyfile @@ -1375,6 +1375,10 @@ INCLUDE_FILE_PATTERNS = # instead of the = operator. PREDEFINED = __attribute__()= \ + __deprecated= \ + __always_inline= \ + __packed = \ + __weak = \ __cplusplus \ STM32_MEDIUM_DENSITY \ STM32_HIGH_DENSITY \ -- cgit v1.2.3