Documenting macros using Doxygen

Question

/** @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?

score 2 · Accepted Answer · answered Feb 17 '17 at 16:27

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.

score 1 · Answer 2 · answered Oct 16 '19 at 00:26

1

It's a bit late, but John's answer is somewhat incomplete. The other thing you could do here is set MACRO_EXPANSION=YES. This has the negative side effect of expanding all macros, though, so the next one to do is EXPAND_ONLY_PREDEF=YES. That limits it to only macros defined in the PREDEFINED section or listed in the EXPAND_AS_DEFINED section. So if you add your macro to that list, it would be the only one expanded.

answered Oct 16 '19 at 00:26

gabe appleton

368
2
10

Is that why I'm seeing the `DECLARE_TYPE`d struct listed under Functions as "DECLARE_TYPE (31)" instead of under the struct section? I added `MACRO_EXPANSION=YES`, but still seeing it listed as a function... – thomthom May 04 '20 at 15:29

Documenting macros using Doxygen

2 Answers2

Linked