Search code examples
cdocumentationdoxygen

Documenting macros using Doxygen

/** @brief This is my initial struct. */
typedef struct
{
    f32   v; /**< Value. */
    int32 s; /**< Scale. */
} f32_t;

#define DECLARE_TYPE(N) \
        typedef f32_t q##N##_t; /**< This is my Q struct. */

DECLARE_TYPE(31)
DECLARE_TYPE(25)

The above code declares a q31_t and q25_t structs. I'd like to document them using Doxygen, but whatever I tried, the structs don't appear in the documentation. They are not even mentioned. Initial struct f32_t is the only one that is documented.

Can this be fixed?

Solution

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