Search code examples
ccommentsdoxygencperl-mode

Document mutually exclusive defines

I'm writing a small program in C and I want to document it so others could change some details. I wrote a config.h file with #defines that enable some operation or not, some of them are mutually exclusive, others aren't.

Example of not mutually exclusive:

#define USE_A
#define USE_B
#define USE_C

Example of mutually exclusive:

#define BUILD_FULL
#define BUILD_COMPACT

Until now I selected the configuration of the program to compile by documenting out the features I don't want to use, for example:

//#define BUILD_FULL
#define BUILD_COMPACT

to build a COMPACT executable.

How can I write documentation for the commented out features?

I tried:

#define USE_A //!< Special Feature
#define USE_B //!< Special Feature
//#define USE_C //!< Special Feature

I compiled it without USE_C but obviously I lost the documentation because doxygen didn't parse it. How would you rewrite the #define flow if I misunderstand the right way of using defines?

Solution

  • You can test for the value of the macro, instead of just its presence. For example, use 0 to disable an option, or 1 to enable it. Then, use #if instead of #ifdef to test the condition.

    #define USE_A 1    //!< Special Feature
#define USE_B 1    //!< Special Feature
#define USE_C 0    //!< Special Feature

#if USE_A
...
#elif USE_C
...
#endif