Doxygen conditional compilation does not produce documentation

Question

I'm a relative beginner with doxygen, and am documenting a C program

Part of the code is:

\#include "options.h"
// options.h contains
\#define VAL0 0   // Possible values for PARAM
\#define VAL1 1
\#define PARAM VAL0

// Here's the conditional compilation
\#if (PARAM == VAL0)
// code chunk, which doesn't get compiled by Doxygen
\#endif

The code compiles with GCC as expected, but I get no Doxygen documentation

OK, Doxygen doesn't expand macros, so I tried:

\#define SYMEQ(A, B) (A == B) ? 1 : 0

\#if SYMEQ(PARAM, VAL0)

// code chunk

\#endif

Set the Doxygen:

MACRO_EXPANSION = YES

EXPAND_ONLY_PREDEF = YES

No Predefined macros

EXPAND_AS_DEFINED = SYMEQ

No doxygen output from the conditional part, just up to it

I also tried EXPAND_AS_DEFINED SYMEQ(A, B)

Also no luck

I found a few examples with simple names, then #ifdef NAME \code #endif, but none with macro functions

Answer 1

I just had the problem #ifdef CONDITION \code not compiled by doxygen\ #endif and fixed it by brute force, i.e, appending the conditions to the setting PREDEFINED=CONDITION1 CONDITION2 ... manually.

I tried the header file solution -- generate a file with conditions and include it by setting SEARCH_INCLUDES, INCLUDE_PATH and INCLUDE_FILE_PATTERNS -- but it did not work. From the doxygen manual, I think it requires to explicitly #include "the condition file" in the source files, which means to modify the source code, so I give up.

SEARCH_INCLUDES: If the SEARCH_INCLUDES tag is set to YES (the default) the includes files in the INCLUDE_PATH (see below) will be searched if a #include is found.

Answer 2

MACRO_EXPANSION and EXPAND_ONLY_PREDEF only control whether a macro will be expanded in your code, not how it will be evaluated in conditional preprocessor blocks. For example, if you had code like:

#define RET_TYPE int

/**
 * Some function
 */
RET_TYPE func(void);

With MACRO_EXPANSION=NO, this will be documented by doxygen as RET_TYPE func(void), the macro isn't expanded. With MACRO_EXPANSION=YES, this will be documented as int func(void), the macro is expanded and the resulting signature is documented.

To control conditional code, you'll want to focus on the ENABLE_PREPROCESSING. If this option is set to NO, conditional code will be ignored, and all code within the condition will be documented. If it is set to YES, the conditional code will be evaluated, and only blocks for which the condition matches will be documented. In this case, you'll need to make sure that all of the values being evaluated are defined correctly, this can be accomplished by allowing doxygen to evaluate include files (see SEARCH_INCLUDES, INCLUDE_PATH and INCLUDE_FILE_PATTERNS options), or by predefining the macros to have a particular value (see PREDEFINED).