doxygen - 成员之后的文档（///<）不起作用答案

【问题标题】：doxygen - documentation after members (///<) does not workdoxygen - 成员之后的文档（///<）不起作用
【发布时间】：2013-04-01 08:52:06
【问题描述】：

嘿嘿，

我正在尝试使用 doxygen 记录我的 C 代码，但是使用“成员之后的文档”样式似乎对我不起作用。 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 void foo(void)

有人知道为什么吗？

【问题讨论】：

标签： c doxygen

【解决方案1】：

成员文档语法适用于成员。

成员是类或结构中的值（或者您的语言可能会这样称呼它）。局部变量是 not 成员，因此不被 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);
}

【讨论】：

感谢您的精彩解释和示例！

【解决方案2】：

Doxygen 允许您记录文件、结构、联合、类或枚举的成员。您显示的代码显示的是方法的局部变量，而不是这些实体之一的成员。

【讨论】：