使用 Doxygen 记录宏答案

【问题标题】：Documenting macros using Doxygen使用 Doxygen 记录宏
【发布时间】：2017-07-07 03:12:37
【问题描述】：

/** @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 是唯一记录在案的结构。

这可以解决吗？

【问题讨论】：

标签： c documentation doxygen

【解决方案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 */

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

这是有道理的，因为预处理器所做的一件事就是将 cmets 转换为空白。 Doxygen 必须以一种导致它忽略宏中的 doc cmets 的方式这样做并不明显，但这样做并非没有道理。

【讨论】：

【解决方案2】：

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

【讨论】：

这就是为什么我看到DECLARE_TYPEd 结构在函数下列为“DECLARE_TYPE (31)”而不是在结构部分下？我添加了MACRO_EXPANSION=YES，但仍将其列为函数...