Documenting Preprocessor Defines in Doxygen

Documenting preprocessor defines in Doxygen

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!

How can I keep doxygen from documenting #defines in a C file?

You can exclude any part of code from Doxygen parsing with \cond ... \endcond tags.

edit: Some related questions:

• How can Doxygen exclude a C++ class?
• Exclude some classes from doxygen documentation

Documenting macros using Doxygen

The primary problem seems to attend putting the documentation comment into the macro. I find that if I put the doc comment with the macro invocation then it is reflected in the generated documentation; otherwise, it is not. Naturally, you have to configure Doxygen to expand macros, which is not its default behavior.

For example:

/** @brief This is my initial struct. */
typedef struct
{
    ae_f32   v; /**< Value. */
    ae_int32 s; /**< Scale. */
} ae_f32_t;

#define DECLARE_TYPE(N) \
        typedef ae_f32_t ae_q##N##_t

DECLARE_TYPE(31); /**< @brief This is my Q31 struct */
DECLARE_TYPE(25); /**< @brief This is my Q25 struct */

(I have also moved the terminating semicolon out of the macro, but with the doc comment also being moved, this is a matter of style only.)

This makes some sense, since one of the things the preprocessor does is convert comments to whitespace. It's not obvious that Doxygen must do that in a way that causes it to ignore doc comments in macros, but it is not unreasonable for it to do so.

---

Related Topics