Documenting preprocessor defines in Doxygen

Question

Is it possible to document preprocessor defines in Doxygen? I expected to be able to do it just like a variable or function, however the Doxygen output appears to have "lost" the documentation for the define, and does not contain the define itself either.

I tried the following

/**My Preprocessor Macro.*/ #define TEST_DEFINE(x) (x*x) 

and

/**@def TEST_DEFINE     My Preprocessor Macro. */ #define TEST_DEFINE(x) (x*x) 

I also tried putting them within a group (tried defgroup, addtogroup and ingroup) rather than just at the "file scope" however that had no effect either (although other items in the group were documented as intended).

I looked through the various Doxygen options, but couldn't see anything that would enable (or prevent) the documentation of defines.

Answer 1

Yes, it is possible. The Doxygen documentation says:

To document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

/*! \file */

or a

/** @file */

line in this file.

You can use @defgroup, @addtogroup, and @ingroup to put related items into the same module, even if they appear in separate files (see documentation here for details). Here's a minimal example that works for me (using Doxygen 1.6.3):

Doxyfile:

# Empty file. 

Test.h:

/** @file */  /**My Preprocessor Macro.*/  #define TEST_DEFINE(x) (x*x)   /**  * @defgroup TEST_GROUP Test Group  *  * @{  */  /** Test AAA documentation. */ #define TEST_AAA (1) /** Test BBB documentation. */ #define TEST_BBB (2) /** Test CCC documentation. */ #define TEST_CCC (3) /** @} */ 

Foo.h:

/** @file */  /**  * @addtogroup TEST_GROUP  *  * @{  */  /** @brief My Class. */      class Foo {     public:         void method(); };  /** @} */ 

Bar.h:

/** @file */  /**  * @ingroup TEST_GROUP  * My Function.  */ void Bar(); 

In this case, the TEST_DEFINE documentation appears in the Test.h entry under the Files tab in the HTML output, and the TEST_AAA etc. definitions appear under Test Group in the Modules tab together with class Foo and function Bar.

One thing to note is that if you put the file name after the @file command, e.g:

/** @file Test.h */ 

then this must match the actual name of the file. If it doesn't, documentation for items in the file won't be generated.

An alternative solution, if you don't want to add @file commands, is to set EXTRACT_ALL = YES in your Doxyfile.

I hope this helps!

Answer 2

In my "C" files, I use a comment format and #define line like this:

/** @brief Number of milli-seconds to wait*/ #define kTimeoutMSec (2) 

My html documents do end up containing documentation I specify. (I do have @file at the top of the file and EXTRACT_ALL=YES)