CODEWITHSUNDEEP
c++macrosdoxygenundefined-symbol
Paul A. Bristow
Paul A. Bristow

Reputation: 191

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

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

Upvotes: 4

Views: 3026

Answers (1)

sifferman
sifferman

Reputation: 3122

Do the following:

  1. Add the following line to your Doxyfile:

    PREDEFINED = _DOXYGEN_

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

Upvotes: 4

Related Questions