我正处于C++项目的开始阶段,我从一开始就一直在使用Doxygen.
我想知道你在项目中如何使用Doxygen,即我有几个问题:
1.你在哪里提出你的Doxygen评论？标题或来源？
我认为他们应该去标题,因为这是我寻找如何使用方法的地方.但是,我想省略原型中的实际参数名称,所以我不能使用@param - 或者我可以吗？你是如何解决这个问题的？
你记录所有方法吗？
到目前为止我只记录公共方法,你是怎么做到的？您是否记录了访问者方法和公共变量？
你总是填写@param和@return吗？
在我工作的地方(它是Javadoc,但它是同一个问题),我们有一个约定只填充实际需要的属性,即如果简短描述说"返回xys if ......",我们省略@return.如果参数名称很明显,我们省略它们.我还不确定我是否喜欢这种方法,你是怎么做到的？到目前为止,我只填写了简介而没有其他内容,但并非所有方法原型都足够简单.
你用哪种风格？
Doxygen中有几种样式:Javadoc(/**... /),QT(/!...*/)等等.纯粹出于兴趣:你使用哪一个？我要使用Javadoc风格的ATM,因为我已经习惯了.
在我的标题中,我有一个这样的原型声明:
void move(int, int);
我可以省略参数名称,这就是我从C中习惯的方法.我这样做是为了让我不必保持参数名称同步 - 如果它们在原型和实现之间有所不同,那就非常混乱了.
现在,我正在使用Doxygen记录我的所有代码,并且我决定将所有注释放入标题中.现在我必须引用在实现中定义但不在头文件中定义的参数名称:我发现这令人困惑.
/**
* Moves the entity to the specified point.
* @param x The x coordinate of the new position.
* @param y The y coordinate of the new position.
*/
void move(int, int);
在生成的Doxygen HTML中,要弄清楚哪个参数是哪个参数并不容易.当然,人们可以遵循相同的顺序,但如果有一个参数,它仍然令人困惑.
另一种方法是复制参数名称并尝试使它们保持同步.但是,有些人不鼓励这种方法,说标题参数应该以双下划线开头,以便方法的用户不可能使用相同的名称(在_C++中不允许以__开头的名称).
你怎么做呢？