Doxygen C++惯例

Question

我正处于 C++ 项目的开始阶段，并且从一开始就一直在使用 Doxygen。

我想知道您在项目中如何使用Doxygen，即我有几个问题：

1。您将 Doxygen 评论放在哪里？标头或来源？

我认为它们应该转到标头，因为这是我查找如何使用方法的地方。但是，我喜欢在原型中省略实际参数名称，因此我不能使用 @param - 或者可以吗？你如何解决这个问题？

2.您是否记录了所有方法？

到目前为止我只记录了公共方法，您是如何做到的？您是否记录了访问器方法和公共变量？

3.你总是填写@param和@return吗？

在我工作的地方（它是Javadoc，但它是同一个问题），我们有一个约定，只填写实际需要的属性，即如果简短的描述说“返回xys if ...”，我们省略@return。如果参数名称很明显，我们将省略它们。我仍然不确定我是否喜欢这种方法，你是怎么做的？到目前为止，我只填写了概要，没有其他任何内容，但并非所有方法原型都足够简单。

4.您使用哪种样式？

Doxygen 中有多种样式：Javadoc (/** ... /)、QT (/! ... */) 等等。纯粹出于兴趣：您使用哪一个？我将使用 Javadoc 风格的 ATM，因为我已经习惯了。

Answer 1

<强>1。您将 Doxygen 评论放在哪里？标题或来源？

我无法回答这个问题，因为我实际上不记得我倾向于在哪里用标头和源来记录。

<强>2。您记录了所有方法吗？

几乎完全是。每个方法都有某种形式的文档，除非从变量/方法名称（以及方法的参数名称）中可以立即明显看出它的具体作用。我倾向于遵循这样的规则：“如果你无法通过名称和参数名称弄清楚方法的用途，则需要注释。如果注释后你仍然无法弄清楚方法的用途，请重写如果您仍然无法很快看出该方法的用途，或者注释“太长”（其中“太长”是任意测量>_>），那么您需要重新编写该方法。或者把它分开。”

<强>3。你总是填写@param和@return吗？

是的。即使从阅读 @brief 中显而易见，或者如果 @return 是 @brief 中句子的精确副本，我仍然填写它们。为方法的文档提供这种扫描属性可能非常有用。 “哦，方法X，我知道它的作用和原因，但是在X情况下它的返回值到底是什么？” *检查@return*。

<强>4。您使用哪种风格？

Javadoc 我自己，尽管这完全是主观的。我使用 Javadoc 语法是因为我花了一段时间用 Java 编写并且非常习惯该语法。我个人也认为它比其他的更有意义——我只是根本不喜欢 QT 语法。

Answer 2

<强>1。您将 Doxygen 评论放在哪里？标题或来源？

文档位于标头中，因为这是定义接口的地方。

<强>2。您记录了所有方法吗？

对于类，我记录了所有公共和受保护的方法，通常只保留私有方法。

<强>3。你总是填写@param和@return吗？

我更喜欢使用内联参数文档

/*!
 * \brief My great class.
 */
class Foo
{
public:
    /*!
     * \brief My great method.
     */
    void method(
        int parameter    //!< [in] parameter does something great
    );
};

而不是使用\param，因为它会导致参数名称重复，并且很容易与当懒惰的开发人员忘记更改 doxygen 时的代码。

当存在 void 返回类型时，\return 被省略。当方法可以抛出时，我总是使用 \throw 。

4.您使用哪种风格？

只要在整个项目中保持一致就可以了。