C++风格的注释

5.4      C++风格的注释

5.4.1    概述

C++的注释风格主要使用下面这种样式：即在注释块开始使用三个反斜杠‘/’

其他地方其实与JavaDoc的风格类似，只是C++风格不用 “*” 罢了。

5.4.2       简述与详述

C++风格的简述与详述方式与javaDoc类似。

一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容，C++风格可以使用的分隔方法有以下两种：

（1）使用 \brief 参数标识，空行作为简述和详述的间隔标识

///     \brief   Brief description.  
///     description continued.  
///  
///     Detailed description starts here.  
/// 

（2） 使用以空行 enum enumEditType

{

enumEditTypeInt=0x1, //只能输入数字。

enumEditTypeChar=0x2, //只能输入字符。

enumEditTypeNormal=0x3, //正常编辑框，可以输入任意字符。

};

typedef struct tagEDITxsl

{

UINT  nMinChar;

UINT nMaxChar;

enumEditType m_edit_type;

std::wstring m_disable_char;

};

（或者小数点加空格）作为简述与详述的分割

///    Brief description  
///    description continued.  
///      
///    Detailed description starts here. 

以小数点加空格作为分隔如下：

///          Brief description  
///          description continued . （注意:这里有一个小数点,加上一个空格）  
///          Detailed description starts here.  
/// 

5.4.3    注释风格约定

1. 一个代码块（类、函数、结构等）的概述采用单行的”///”加一个空格开头的注释，并写在该代码块声明的前面；
2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释，若不足两行第二行的开头也要写出来，并且放在代码块定义的前面；如果某代码没有声明只有定义或者相反，则在定义或者声明前面写上单行的概述+一个空行+多行的详述；
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释；
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释（相当于是给改变量一个概述）；
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面；
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面；
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面；
8. 文件头的版权以及文件描述的注释参见例代码。

5.4.4       文件头注释示例

//////////////////////////////////////////////////////////////////////////  
///     COPYRIGHT NOTICE  
///     Copyright (c) 2009, 华中科技大学      （版权声明）  
///     All rights reserved.  
///  
/// @file     （本文件的文件名eg：Test.h）  
/// @brief （本文件实现的功能的简述）  
///  
///（本文件实现的功能的详述）  
///  
/// @version 1.1      （版本声明）  
/// @author             （作者，eg：卢俊）  
/// @date                 （文件创建日期，eg：2009年7月15日）  
///  
///  
///     修订说明：最初版本  
////////////////////////////////////////////////////////////////////////// 

5.4.5       类定义注释示例

///     本类的功能：打印错误信息  
///  
///     本类是一个单件  
///     在程序中需要进行错误信息打印的地方  
class CPrintError  
{  
           ……  
}  

5.4.6       类成员变量定义示例

（1）在成员变量上面加注释的格式

/// 成员变量描述  
int   m_Var; 

（2）在成员变量后面加注释的格式

int   m_color;     /// 颜色变量    

5.4.7       成员函数的注释示例

/// 下面是一个含有两个参数的函数的注释说明（简述）   
///     
///      这里写该函数的详述信息     
///      @param a 被测试的变量（param描述参数）     
///      @param s 指向描述测试信息的字符串     
///      @return     测试结果 （return描述返回值）   
///      @see     Test()     （本函数参考其它的相关的函数，这里作一个链接）  
///      @note     (note描述需要注意的问题)     
int testMe(int a,const char *s);  

5.4.8       枚举变量的注释示例

///     颜色的枚举定义  
///   
///     该枚举定义了系统中需要用到的颜色\n  
///     可以使用该枚举作为系统中颜色的标识  
enum TEnum   
{   
     RED,            ///< 枚举，标识红色        
     BLUE,           ///< 枚举，标志蓝色        
     YELLOW          ///< 枚举，标志黄色.        
}enumVar;     

5.5     需要注意的问题

（1）Doxygen会忽略你在注释中加入的多余的换行，如果你希望保留两行注释之间的空行，那么，在该行加入 \n

6      Doxygen使用的常见问题小结

6.1     中文问题：中文注释在文档中是乱码

解决：在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。

6.2    图形问题：无法绘制类图协作图等图形。

解决：首先确保安装了graphviz for win，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。

如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。

6.3    输出chm的问题：如何输出.chm文件

配置时注意expert中的HTML页：选中“GENERATE_HTMLHELP”，然后在CHM_FILE中填上想要的chm文件名。

HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。

或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件，编译完成后即可在该html文件夹中找到对应的chm文件

6.4     Doxygen无法为DLL中定义的类 导出文档

例如：

class __declspec(dllexport) CClassName:public CObject

{

}

目前发现Doxygen无法识别出DLL中定义的类。