Doxygen C++约定

Question

我正处于C++项目的开始阶段,我从一开始就一直在使用Doxygen.

我想知道你在项目中如何使用Doxygen,即我有几个问题:

1.你在哪里提出你的Doxygen评论？标题或来源？

我认为他们应该去标题,因为这是我寻找如何使用方法的地方.但是,我想省略原型中的实际参数名称,所以我不能使用@param - 或者我可以吗？你是如何解决这个问题的？

你记录所有方法吗？

到目前为止我只记录公共方法,你是怎么做到的？您是否记录了访问者方法和公共变量？

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

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

你用哪种风格？

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

Answer 1

1.你在哪里提出你的Doxygen评论？标题或来源？

我无法回答这个问题,因为我实际上目前还不记得我倾向于在标题与来源方面记录的位置.

你记录所有方法吗？

几乎完全是的.每个方法都会获得某种形式的文档,除非从变量/方法名称(以及方法的参数名称)中可以立即看出它在具体内容中的作用.我倾向于遵循"如果你不能通过它的名称和参数名称来解决方法的目的,它需要一个注释.如果在评论之后你仍然无法解决方法的目的,重写如果你仍然无法很快看到方法的目的,或者评论是"太长"("太长"是一个任意的测量> _>),那么你需要重新编写方法或者分开了."

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

是.即使从阅读中看起来很明显@brief,或者如果它@return是一个精确的句子副本@brief,我仍然填写它们.对于方法的文档来说,拥有那种扫描属性是非常有用的."哦,方法X,我知道它的作用和原因,但它在X情况下的返回值究竟是什么呢？"*检查@return*.

你用哪种风格？

Javadoc自己,虽然这是完全主观的.我使用Javadoc语法,因为我花了一些时间用Java编写并且习惯了这种语法.我个人认为它比其他人更有意义 - 我根本不喜欢QT语法.

Answer 2

1.你在哪里提出你的Doxygen评论？标题或来源？

文档位于标题中,因为这是定义接口的位置.

你记录所有方法吗？

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

你总是填写@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在方法可以抛出时使用.

你用哪种风格？

只要它在整个项目中一致无所谓.