doxygen从c++注释生成设计说明
对于大多数写代码的人来说,写文档是一件既让人感觉“没有技术含量”、枯索无味而又冗长的事情。特别是设计说明这种马后炮类的文档,几乎到了让人感觉到痛苦的地步。
而如今新的IDE、新的技术涌现,已经解决了部分文档的问题,也就是代码文档化。代码文档化不仅是一种时髦、漂亮,也不仅仅停留在编程规范纸上空文的层次,而俨然成为了猿猿们的一种关乎进度时间、能否正常下班的几乎刚性的需求了。
c++可文档化注释格式
分下类吧,1、变量注释。2、函数方法注释。3、结构体注释。
简要注释的n种格式
1、
/**
*@brief comment
*/
2、
/// comment
3、
//! comment
详细注释的n种格式
1、
/**
* … text …
*/
2、
/*!
… text …
*/
3、
///
/// … text …
///
4、
/
/// … text …
/
函数注释
/**
* @brief doSomeFuncT
* @param val
* @param bIf HEAD HEHE
* @return HEAD HOW TO DEAL IT
*/
int doSomeFuncT(int val,bool bIf);
默认用javadoc格式的注释肯定可以识别的。有个注意事项,如果头文件与源文件都写了,会生成2份方法说明注释,头源文件对应的各一份。
结构体成员注释
/**
* @brief The St_forExample struct
*/
struct St_forExample{
int nId; ///<id
char chChannel; ///<通道号
bool bDoOrNot; ///<是否操作
};
///< comment
用上面的加到语句行尾即可完成注释。
doxygen的使用
windows版本的有界面,选一下,配置一些选项即可。我想,对于娴熟于软件开发,周游于各种IDE之间,聪明如你,肯定会摸清楚这个软件的下载、使用方法的。:)。
版本:windows 1.8.12
如上图所示,选下代码目录,windows下的如果没有切换操作系统成英文,老实把第一行编码改成GBK吧。:)。
专家栏目中,把rtf选择选上。
最后选run栏目,点下生成。就会在代码目录下看到多出了几个文件夹。rtf下有生成的文档,可转成word格式的。
还有一个html的索引页,可以索引到各个类、文件进行浏览。
几个效果图如下:
生成的文档简图。
网页索引界面。
最后,写注释的重要性是不言而喻的。那么既然写还是按规范写好注释吧,总会有那么些时候让自己感觉省时省力的。 :)