Doxygen: How can I document macros that are not #defined?

Question

I am trying to use Doxygen to document the functions of some option-controlling macros symbols, for example:

 //! \def BOOST_SOMEFEATURE
 /*! \brief Option macro that is not normally defined
  *  but can optionally be defined by consumers to activate the option.
 */

But this will NOT be indexed and the comment will be ignored because the macro isn't defined.

A Doxygen macro symbol entry will only be produced in the documentation when there is a #define like

#define BOOST_SOMEFEATURE

in the header and other files.

Can I force documentation of the macro symbol other than by nasty fudges like

  #undef BOOST_SOMEFEATURE

or perhaps including a dummy .cpp file that contains #defines for all the macro symbols that control options?

  #define BOOST_SOMEFEATURE
  #define BOOST_SOMEOTHERFEATURE
  ...

At least when I understand your question well it should be possible to make a block around these definitions and documentation with e.g. #ifdef DOXYGEN_GENERATION and define DOXYGEN_GENERATION in your Doxyfile. — albert, Jan 30 '16 at 09:56
Thanks. Sounds plausible, but I don't yet understand how I can #define BOOST_SOMEFEATURE in the doxyfile so that it will be indexed by Doxygen. Please can you explain a bit more? — Paul A. Bristow, Feb 01 '16 at 17:51

score 4 · Answer 1 · edited Mar 24 '19 at 18:15

Do the following:

Add the following line to your Doxyfile:
```
PREDEFINED = _DOXYGEN_
```

Put your #define macros inside an #ifdef _DOXYGEN_ section:

#ifdef _DOXYGEN_
    /*!
     * Documentation describing the BOOST_SOMEFEATURE macro.
     */
    #define BOOST_SOMEFEATURE

    /*!
     * Documentation describing the BOOST_SOMEOTHERFEATURE macro.
     */
    #define BOOST_SOMEOTHERFEATURE
#endif

With this method, your macros will not be seen by the preprocessor during a normal build, but will be seen by Doxygen.

You can put this section anywhere in your code that you like: in a .cpp file, a .h file, or create a dummy .cpp file if you like.

See also

Thanks for this - works nicely for me in the header file, allowing me to keep the documentation with the code. — Paul A. Bristow, Feb 02 '16 at 16:42

Doxygen: How can I document macros that are not #defined?

1 Answers1