是否有减少完全Doxygen覆盖所需的冗余评论量的技巧？

Question

作为记录我的C++代码库的一部分,我正在努力获得完整的Doxygen覆盖 - 也就是说,我希望我的所有(数百个)头文件都为其所有公共API提供格式良好的Doxygen注释,以便我可以在代码库上运行Doxygen而不会看到任何"警告:没有记录的blah"警告.

一般来说,这只是一个记录和记录内容的问题,但我注意到我一直在为每个课程反复输入相同的文本.例如,我有很多基本上这样的实例:

/** The Foo class represents blah blah blah */
class Foo
{
public:
    /** Default constructor */
    Foo();

    /** Copy constructor
      * @param rhs the object to make this object a copy of.
      */
    Foo(const Foo & rhs);

    /** Destructor */
    ~Foo();

    /** Equality operator.
      * @param rhs the object to compare against.
      * @returns true iff this object and (rhs) are equal.
      */
    bool operator == (const Foo & rhs) const;

    /** Inequality operator.
      * @param rhs the object to compare against.
      * @returns true iff this object and (rhs) are not equal.
      */
    bool operator != (const Foo & rhs) const;

    /** Assignment operator
      * @param rhs the object we should copy our state from
      * @returns a reference to *this
      */
    Foo & operator = (const Foo & rhs);

[...]
}

对于每个类,这些注释(通常)或多或少完全相同,因为这些函数/运算符几乎总是对每个类的工作方式完全相同.实际上,拥有以其他方式运行的运算符或复制构造函数将是一个有问题的设计模式,因为C++程序员通常希望运算符以相同的方式为每个类工作.

我的问题是,是否有一些技巧可以告诉Doxygen为这些事情自动生成合理的文档(例如通过某种模板或宏),而不必一次又一次地手动输入这个文本？这将大大减少我必须输入和维护的文本数量,并且通过允许我删除"no duh"变体的注释以使读者可以更容易地找到注释,这也会使我的头文件变得杂乱无章.提供真正的洞察力.

Answer 1

有几个用于复制文档的命令：

\copydoc \copybrief \copydetails

Doxygen 帮助建议使用以下语法：

/*! @copydoc MyClass::myfunction()
 *  More documentation.
 */

这允许您将文档从一个类复制到另一个类。有时，我生成一个仅包含文档的类，该类未编译为在项目的其余部分中提取文档的标准位置。