使用Doxygen记录宏 [英] Documenting macros using 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屋!