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?

John Bollinger · Accepted Answer · 2017-02-17 16:27:04Z

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.

gabe appleton · Accepted Answer · 2019-10-16 00:26:43Z

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, 2019 at 0:26

gabe appleton

3782 silver badges10 bronze badges

1 Comment

thomthom Over a year ago

Is that why I'm seeing the DECLARE_TYPEd 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...

Collectives™ on Stack Overflow

Documenting macros using Doxygen

2 Answers 2

Comments

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related