使用 doxygen 记录结构定义之外的 c 结构的成员答案

【问题标题】：Use doxygen to document members of a c structure outside of the structure definition使用 doxygen 记录结构定义之外的 c 结构的成员
【发布时间】：2011-11-04 04:14:38
【问题描述】：

我正在使用 doxygen 来注释我的 C 代码。我正在使用文档稀缺的外国 API（即不是我自己的），因此我打算在我自己的源文件中记录一些该 API。我确实有外部 API 的头文件，但将我自己的 cmets 添加到该文件是不切实际的。

外文标题

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 生成的输出相同）？

【问题讨论】：

标签： c doxygen

【解决方案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...
 */

【讨论】：

如果foreignstruct 位于由 doxygen 解析的文件中，则此解决方案有效。如果 doxygen 不知道该文件，您是否希望它能够工作？当找不到外部结构定义时，我看到warning: no uniquely matching class member found for foreignstruct::a（这是正确的，因为我不希望 doxygen 解析该外部标头）。我尝试将路径添加到标题 (@struct foreignstruct /full/path/to/header.h) 但我得到了 warning: the name full/path/to/header.h' 作为 \class、\struct、\union 或 \include 命令的参数提供不是输入文件。
doxygen 确实应该知道该结构。因此，除了本地文档之外，您可以让 doxygen 解析外部标头，也可以在本地添加带有字段的结构的虚拟定义（但您不必使用 @struct 和 @var）。
不是我希望的答案，但这是我期待的答案。感谢您的帮助。