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???

Hintz

Probably the best solution does not #define what you need to #undef-ine. From my experience #undef is used only to do tricks/hacks – Germainegerman

It is sort of a hack. I want to code out large amount of code that deals with specialized hardware that is not installed on the development machine, yet easily enable it when it needs to run on the actual target machine. – Hintz

As a really big warning about undef - I once fixed a bug for Apple that had been outstanding for 18 months. The Quicktime headers relied on being included recursively with conditional definitions and the traditional guard variables being undef'd. At some later point, someone had added the #pragma once which meant the compiler broke the recursive inclusion. – Crossgrained

Answer 1

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.

Crossgrained

Answer 2

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.

Hintz

BTW, it looks weird (and some static analysers may notice that) – Germainegerman

I agree with you. It's just one work around. I'm hoping someone will know how to force doxygen to document an #undef. – Hintz

Answer 3

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

Irvingirwin