Good way to document #undef in doxygen

Question

I currently have a couple of #define in c files that turn off some functionality to hardware for testing. However, I want to document them with doxygen when they are undefined as well.

For example:

This works fine:

/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE

When you change the #define to #undef, you get a warning in doxygen, and it doesn't show up in the doxygen generated output. I want to document this #define wether it's defined or undefined.

How can I force doxygen to document a #undef???

Answer 1

I solved my problem with documenting compilerflags like this in the main headerfile:

/**
 * \defgroup flags Compilerflags
 */

/**
 * \def MY_FLAG
 * \ingroup flags
 * Dokumentation....
 */
#ifndef MY_FLAG
#define MY_FLAG
#undef MY_FLAG
#else
#define MY_FLAG
#endif

This way everything works fine: doxygen and compiling and you can keep specifying your flags in commandline...

Answer 2

Define them in a header file that is only included by Doxygen (put in a separate directory tree from the main source).

Guard this header file by wrapping it with a define that you only define in the Doxygen setup, eg:

#ifdef ONLY_FOR_DOXYGEN

/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE

#endif

I have used this to also conditionally include lightweight class definitions for things like MFC base classes so they appear as bases for the class hierarchy without having to parse all of MFC.

Answer 3

I found a kludgy way by adding the #undef under the #define. This way it's defined for Doxygen, but immediately undefined for the compiler.

/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
/// Comment out #undef to simulate HW interface
#define SIMULATE_SOME_HW_INTERFACE
#undef  SIMULATE_SOME_HW_INTERFACE

I was trying to figure out how to set SIMULATE_HW_INTERFACE in the Doxyconfig file using PREDEFINED option. Couldn't get it to work. So here's my best solution so far.