使用Doxygen记录宏 [英] Documenting macros using Doxygen

查看:97
本文介绍了使用Doxygen记录宏的处理方法,对大家解决问题具有一定的参考价值,需要的朋友们下面随着小编来一起学习吧!

问题描述

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

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.

这可以解决吗?

推荐答案

主要问题似乎在于将文档注释放入宏中.我发现,如果我在文档注释中加入宏 invocation ,则该注释会反映在生成的文档中;否则,事实并非如此.自然,您必须配置Doxygen来扩展宏,这不是它的默认行为.

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.

例如:

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

这是有道理的,因为预处理器要做的一件事就是将注释转换为空格.Doxygen必须以某种方式使其忽略宏中的文档注释,这一点并不明显,但这样做并非不合理.

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.

这篇关于使用Doxygen记录宏的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!

查看全文
登录 关闭
扫码关注1秒登录
发送“验证码”获取 | 15天全站免登陆