和雅
我试图用doxygen来记录我的C代码,但是使用“documentation after members”样式似乎对我不起作用doxygen文档说:
在成员之后放置文档
如果要记录文件、结构、联合、类或枚举的成员,有时需要将文档块放在成员之后,而不是放在成员之前。为此,必须在注释块中添加一个下面是一些例子:
[...]
大多数情况下,人们只想在一个成员后面加上简短的描述具体操作如下:
int var; //!< Brief description after the member
或
int var; ///< Brief description after the member
最小源示例:
/** @file test.c */
void foo(void) {
uint8_t bar; ///< Some random variable
}
我的Doxyfile是pasted here。
我得到的不是文档中对变量的一些描述,而是:
2.1.1功能文件
2.1.1.1无效foo(void)
有人知道为什么吗?
最佳答案
成员文档语法是为成员准备的。
成员是类或结构中的值(或者您的语言可能会调用它)局部变量不是成员,因此不被doxygen覆盖。
这样做的原因是,通常类的成员对其状态至关重要,因此您非常希望记录这些成员,因为派生类可能使用受保护的成员(例如)。
另一方面,函数的局部变量不需要这样的文档毕竟,这些都是本地的因此,一个函数应该由其全部可观察的行为来定义,因为局部变量对用户并不重要:
struct object_type{
struct object_state_type state; ///< the object's state
};
void bad_documentation(void) {
uint8_t bar; ///< Some random variable
}
/// \brief Initializes the global state of the omnipotence object.
void good_documentation(void) {
uint8_t bar;
/** \remark The object needs to be initialized exactly once,
* otherwise we have some problems.
*/
assert(some_global_var != 0);
/** One can check `some_global_var` whether the global object
* has been initialized
*/
some_global_var = 1;
/// Finally, the object going to be initialized.
impl_obj_state_init(&the_global_object.state);
}
关于c - doxygen-成员(///<)之后的文档不起作用,我们在Stack Overflow上找到一个类似的问题:https://stackoverflow.com/questions/15910180/