首页 文章

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

提问于
浏览 次
1

部屋，

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

在成员之后放置文档如果要记录文件，结构，联合，类或枚举的成员，有时需要将文档块放在成员之后而不是之前 . 为此，您必须在注释块中添加一个<标记 . 请注意，这也适用于函数的参数 . 以下是一些例子：[...]大多数情况下，人们只想在会员后面做一个简短的描述 . 这样做如下：int var; //！<会员后的简要说明
或者int var; /// <会员后的简要说明

最佳源代码示例：

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

2 回答

  • 2

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

    回复于
  • 5

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

    成员是类或结构中的值（或者您的语言可能称之为） . 局部变量不是成员，因此不受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);
}
    回复于

相关问题