c - doxygen - 成员 (///<) 之后的文档不起作用

Question

嘿呀，

我正在尝试用 doxygen 记录我的 C 代码，但是使用“在成员之后记录”风格似乎对我不起作用。 doxygen 文档说:

Putting documentation after members

If you want to document the members of a file, struct, union, class, or enum, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.

Here are some examples:

[...]

Most often one only wants to put a brief description after a member. This is done as follows:

int var; //!< Brief description after the member

or

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 Function Documentation

2.1.1.1 void foo ( void )

< Some random variable

有人碰巧知道为什么吗？

Answer 1

成员文档语法是为成员准备的。

成员是类或结构中的值(或者您的语言可能这样调用它)。局部变量不是成员，因此不在 doxygen 范围内。

这样做的原因是，通常类的成员对其状态至关重要，因此您迫切希望记录这些，因为派生类可能会使用 protected 成员。

另一方面，函数的局部变量不需要这样的文档。毕竟，这些都是本地。因此，一个函数应该由它的总可观察行为来定义，因为局部变量对用户来说并不重要:

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);
}