对于大多数写代码的人来说，写文档是一件既让人感觉“没有技术含量”、枯索无味而又冗长的事情。特别是设计说明这种马后炮类的文档，几乎到了让人感觉到痛苦的地步。

而如今新的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);

• 1
• 2
• 3
• 4
• 5
• 6
• 7

默认用javadoc格式的注释肯定可以识别的。有个注意事项，如果头文件与源文件都写了，会生成2份方法说明注释，头源文件对应的各一份。

结构体成员注释

/**
 * @brief The St_forExample struct
 */
struct St_forExample{
    int nId;            ///<id
    char chChannel;     ///<通道号
    bool bDoOrNot;      ///<是否操作
};

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8

///< comment

用上面的加到语句行尾即可完成注释。

doxygen的使用

windows版本的有界面，选一下，配置一些选项即可。我想，对于娴熟于软件开发，周游于各种IDE之间，聪明如你，肯定会摸清楚这个软件的下载、使用方法的。：）。
版本：windows 1.8.12

如上图所示，选下代码目录，windows下的如果没有切换操作系统成英文，老实把第一行编码改成GBK吧。：）。
专家栏目中，把rtf选择选上。
最后选run栏目，点下生成。就会在代码目录下看到多出了几个文件夹。rtf下有生成的文档，可转成word格式的。
还有一个html的索引页，可以索引到各个类、文件进行浏览。

几个效果图如下：

生成的文档简图。

网页索引界面。

最后，写注释的重要性是不言而喻的。那么既然写还是按规范写好注释吧，总会有那么些时候让自己感觉省时省力的。 ：）

doxygen从c++注释生成设计说明