将在一行中声明的成员记录在一起，而不创建组

Documenting together members declared on one line without creating a group

本文关键字：在一起 记录 成员 创建组 声明 一行      更新时间：2023-10-16

考虑：

struct S {
    ... // Some data members
    double x, y; ///< Coordinates
    ... // More data members
}

doxygfen将我为x和y准备的注释解释为仅指y（或者，至少在最终文档中没有指示它指的是两者）。我可以用两种方法解决这个问题：

  • 重复注释。然而，这将需要在单独的行上声明x和y，这是不太可读的，因为这些成员在逻辑上是相关的。

  • 创建一个组。然而，在这种情况下，x和y将出现在文档中的所有其他数据成员之后，如果数据成员出现的特定顺序存在逻辑，则这可能是不希望的。

有没有一种方法可以评论在一行中声明的成员不具备上述方法的弱点？

Imho通常每行声明一个变量是一种很好的做法。这避免了一些混淆，例如

int* x,y;

除其他外。我真的不理解你对"可读性较差，因为这些成员在逻辑上是相关的"的担忧。它们包含在同一个结构中，因为它们在逻辑上是相关的。如果你想更清楚，就做一个

struct XY {
    double x; 
    double y;
}

我知道这并不能真正回答你的问题，但当我寻找它时，我没有找到一种使用doxygen为在一行中声明的2个（或更多）变量提供注释的方法。我看不出你提到的第一种方法的弱点，因为它无论如何都会使代码更可读。

问题的正确答案是：将坐标封装为一种类型，如：

struct Point 
{
   double x;
   double y;
};

然后问题消失：

struct S {
    ... // Some data members
    Point coordinates; ///< Coordinates
    ... // More data members
};

也许在那次改变之后，评论就不再那么必要了。。。

我看不出有什么问题；

struct Point 
{
   double x;  ///< x & y are coordinates. (more detailed description)
   double y;  ///< See "x".
};

在doxygen中，有一些复制项目copy...的文档的可能性，链接到其他文档也是可能的ref link ... endlink。

有了copydoc，我们可以到达这里：

struct Point 
{
   double x;  ///< x & y are coordinates. (more detailed description)
   double y;  ///< copydoc Point::x
};
相关文章：