使用 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)

上面的代码声明了一个 q31_t 和 q25_t 结构。我想使用 Doxygen 记录它们，但无论我尝试什么，这些结构都没有出现在文档中。他们甚至没有被提及。初始结构 f32_t 是唯一被记录的结构。

这可以修复吗？

Answer 1

主要问题似乎是将文档注释放入宏中。我发现如果我将文档注释与宏 invocation 放在一起，那么它会反映在生成的文档中；否则，它不是。当然，您必须配置 Doxygen 来扩展宏，这不是它的默认行为。

例如：

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

（我也将终止分号移出宏，但文档注释也被移动，这只是样式问题。）

这是有道理的，因为预处理器所做的其中一件事就是将注释转换为空白。 Doxygen 必须以忽略宏中的文档注释的方式执行此操作并不明显，但这样做并非没有道理。

Answer 2

有点晚了，但约翰的回答有些不完整。您可以在这里做的另一件事是设置 MACRO_EXPANSION=YES。但是，这具有扩展 all 宏的负面影响，因此下一个要做的是 EXPAND_ONLY_PREDEF=YES。这将其限制为仅在 PREDEFINED 部分中定义或在 EXPAND_AS_DEFINED 部分中列出的宏。因此，如果您将宏添加到该列表，它将是唯一展开的宏。

使用 Doxygen 记录宏

Documenting macros using Doxygen

c

documentation

doxygen