使用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是唯一被记录的。这个问题可以修复吗？

- Danijel

Answer 1

主要问题似乎在于将文档注释放入宏中。我发现，如果我将文档注释与宏调用一起放置，则会在生成的文档中反映出来；否则，就不会反映出来。当然，您需要配置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必须以一种使其忽略宏中的文档注释的方式进行转换，但这样做并不是不合理的。

- John Bollinger

Answer 2

这里稍微晚了一些，但是John的回答有点不完整。你还可以在这里设置MACRO_EXPANSION=YES。这样做的负面影响是扩展所有宏，因此下一步是设置EXPAND_ONLY_PREDEF=YES。这将限制仅扩展在PREDEFINED部分中定义或在EXPAND_AS_DEFINED部分中列出的宏。因此，如果您将您的宏添加到该列表中，则它将是唯一扩展的宏。

- gabe appleton

---

这就是为什么我看到 DECLARE_TYPE 结构在函数列表中显示为 "DECLARE_TYPE (31)" 而不是在结构部分下面的原因吗？我添加了 MACRO_EXPANSION=YES，但仍然将其列为函数... - thomthom