Doxygen C++ 约定

Question

我刚开始一个 C++ 项目，我从一开始就一直在使用 Doxygen。

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

1.您将 Doxygen cmets 放在哪里？标题或来源？

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

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

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

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

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

4.您使用哪种风格？

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

Answer 1

1.您将 Doxygen cmets 放在哪里？标题或来源？

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

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

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

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

是的。即使从阅读@brief 中可以看出非常明显，或者如果@return 是@brief 中句子的精确副本，我仍然会填写它们。将这种扫描属性用于方法的文档。 “哦，方法X，我知道它的作用和原因，但它在X情况下的返回值到底是多少？” *检查@return*。

4.您使用哪种风格？

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

Answer 2

1.您将 Doxygen cmets 放在哪里？标题或来源？

文档放在标题中，因为这是定义接口的地方。

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 时，很容易与代码不同步。

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

4.您使用哪种风格？

没关系，只要在整个项目中保持一致即可。