使用doxygen来记录C结构体定义外的成员。

Question

我正在使用doxygen为我的C代码进行注释。我正在使用一个外部API（即不是我的）, 该API的文档很少，因此我打算在自己的源文件中记录一些该API的信息。我确实拥有外部API的头文件，但将我的注释添加到该文件中并不实用。

外部头文件

struct foreignstruct
{
    int a;
    int b;
};

我的标题

/** My structure comments... */
struct mystruct
{
    /** Describe field here... */
    int field;
};

/** @struct foreignstruct
 *  @brief This structure blah blah blah...
 *  @??? a Member 'a' contains...
 *  @??? b Member 'b' contains...
 */

我应该使用什么标签来代替@???以获得正确的Doxygen输出（其中“正确”表示生成的mystruct和foreignstruct的输出相同）？

- Ben

Answer 1

或许有一天doxygen会为此专门设计一个 @field 标签，但在那之前，可以使用以下方法：

/** @struct foreignstruct
 *  @brief This structure blah blah blah...
 *  @var foreignstruct::a 
 *  Member 'a' contains...
 *  @var foreignstruct::b 
 *  Member 'b' contains...
 */

这是一个简写符号，表示

/** @struct foreignstruct
 *  @brief This structure blah blah blah...
 */
/** @var foreignstruct::a 
 *  Member 'a' contains...
 */
/** @var foreignstruct::b 
 *  Member 'b' contains...
 */

- doxygen

---

如果 foreignstruct 在被 doxygen 解析的文件中，那么此解决方案就可行。如果该文件未被 doxygen 所知，您认为它会起作用吗？当找不到 foreignstruct 的定义时（这是正确的，因为我不想让 doxygen 解析那个外部头文件），我看到 warning: no uniquely matching class member found for foreignstruct::a。我尝试添加头文件的路径(@struct foreignstruct /full/path/to/header.h)，但是我收到了警告信息：warning: the name full/path/to/header.h' supplied as the argument of the \class, \struct, \union, or \include command is not an input file`。 - Ben

结构体确实应该被Doxygen所知道。因此，您可以让Doxygen解析外部头文件以及本地文档，或者在本地添加一个带有字段的虚拟结构体定义（但这样您就不必使用@struct和@var）。 - doxygen

不是我希望得到的答案，但这正是我所期待的答案。感谢您的帮助。 - Ben