5      Doxygen的注释风格

5.1   综述

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed 两种都是可选的,但不能同时没有。
顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。
Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等,下面将分别予以介绍。
若需要通过Doxygen生成漂亮的文档,一般有如下几个地方需要使用Doxygen支持的风格进行注释:
    1) 文件头(包括.h和.cpp)
        主要用于声明版权,描述本文件实现的功能,以及文件版本信息等
    2) 类的定义
        主要用于描述该类的功能,同时也可以包含使用方法或者注意事项的简要描述
    3) 类的成员变量定义
        在类的成员变量上方,对该成员变量进行简要地描述
    4) 类的成员函数定义
        在类定义的成员函数上方,对该成员函数功能进行简要描述
    5) 函数的实现在函数的实现代码处,详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等
 

5.2    Doxygen支持的指令

5.2.1   概述

可以在注释中加一些Doxygen支持的指令,主要作用是控制输出文档的排版格式,使用这些指令时需要在前面加上“\”或者“@”(JavaDoc风格)符号,告诉Doxygen这些是一些特殊的指令,通过加入这些指令以及配备相应的文字,可以生成更加丰富的文档,下面对比较常用的指令做一下简单介绍。

5.2.2   常用指令介绍

@file
档案的批注说明。
@author
作者的信息
@brief
用于class function的简易说明
eg
@brief 本函数负责打印错误信息串
@param
主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明
@return
描述该函数的返回值情况
eg:
@return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE
@retval
描述返回值类型
eg:
@retval NULL 空字符串。
@retval !NULL 非空字符串。
注解
@attention
注意
@warning
警告信息
@enum
引用了某个枚举,Doxygen会在该枚举处产生一个链接
eg
@enum CTest::MyEnum
@var
引用了某个变量,Doxygen会在该枚举处产生一个链接
eg
@var CTest::m_FileKey
@class
引用某个类,
格式:@class <name> [<header-file>] [<header-name>]
eg:
@class CTest "inc/class.h"
@exception
可能产生的异常描述
eg:
@exception 本函数执行可能会产生超出范围的异常
 

5.3      JavaDoc风格的注释

5.3.1    概述

JavaDoc风格的注释风格主要使用下面这种样式:即在注释块开始使用两个星号*
 
  1. /**   description      
  2.  *    description      
  3.  *    description      
  4.  */

5.3.2    简述与详述的方式

Doxygen支持的块(类、函数、结构体等)的注释描述分为两种:简述 详述
一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,javaDoc风格可以使用的分隔方法有以下两种:
1)       使用 \brief 参数标识,空行作为简述和详述的间隔标识
  1. /*!    @brief  Brief description.  
  2.  *    description continued.  
  3.  *  
  4.  *    Detailed description starts here.  
  5.  */ 

2 直接使用javaDoc风格,javaDoc风格自动以简述开头,以空行(或者小数点加空格)作为简述与详述的分割

  1. /**    Brief description  
  2.  *    description continued  
  3.  *  
  4.  *    Detailed description starts here.  
  5.  */ 
  1.  
  2. /**        Brief description  
  3.  *         description continued . (注意:这里有一个小数点,加上一个空格)  
  4.  *         Detailed description starts here.  
  5.  */ 

5.3.3   文件头注释示例

5.3.4   类定义注释示例

  1. /**    本类的功能:打印错误信息  
  2.  *   
  3.  *     本类是一个单件  
  4.  *     在程序中需要进行错误信息打印的地方  
  5.  */ 
  6. class CPrintError  
  7. {  
  8.             ……  

5.3.5   类成员变量定义示例

1)在成员变量上面加注释的格式
  1. /** 成员变量描述 */ 
  2. int  m_Var; 
2)在成员变量后面加注释的格式
  1. int  m_color;     /**< 颜色变量 */     

5.3.6   成员函数的注释示例

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

5.3.7     枚举变量的注释示例

  1. /**    颜色的枚举定义  
  2.   *   
  3.   *    该枚举定义了系统中需要用到的颜色\n  
  4.   *    可以使用该枚举作为系统中颜色的标识  
  5.   */ 
  6. enum TEnum   
  7. {   
  8.      RED,           /**< 枚举,标识红色    */      
  9.      BLUE,          /**< 枚举,标志蓝色    */      
  10.      YELLOW         /**< 枚举,标志×××. */      
  11. }enumVar;    

5.4      C++风格的注释

5.4.1    概述

C++的注释风格主要使用下面这种样式:即在注释块开始使用三个反斜杠/
其他地方其实与JavaDoc的风格类似,只是C++风格不用 * 罢了。

5.4.2       简述与详述

C++风格的简述与详述方式与javaDoc类似。
一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,C++风格可以使用的分隔方法有以下两种:
(1)使用 \brief 参数标识,空行作为简述和详述的间隔标识
 
  1. ///    \brief  Brief description.  
  2. ///    description continued.  
  3. ///  
  4. ///    Detailed description starts here.  
  5. /// 
2 使用以空行(或者小数点加空格)作为简述与详述的分割
 
  1. ///   Brief description  
  2. ///   description continued.  
  3. ///     
  4. ///   Detailed description starts here. 
以小数点加空格作为分隔如下:
  1. ///         Brief description  
  2. ///         description continued . (注意:这里有一个小数点,加上一个空格)  
  3. ///         Detailed description starts here.  
  4. /// 

5.4.3    注释风格约定

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

5.4.4       文件头注释示例

5.4.5       类定义注释示例

  1. ///    本类的功能:打印错误信息  
  2. ///  
  3. ///    本类是一个单件  
  4. ///    在程序中需要进行错误信息打印的地方  
  5. class CPrintError  
  6. {  
  7.           ……  
  8. }  

5.4.6       类成员变量定义示例

1)在成员变量上面加注释的格式
  1. /// 成员变量描述  
  2. int  m_Var; 
2)在成员变量后面加注释的格式
  1. int  m_color;     /// 颜色变量    

5.4.7       成员函数的注释示例

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

5.4.8       枚举变量的注释示例

 
  1. ///    颜色的枚举定义  
  2. ///   
  3. ///    该枚举定义了系统中需要用到的颜色\n  
  4. ///    可以使用该枚举作为系统中颜色的标识  
  5. enum TEnum   
  6. {   
  7.     RED,            ///< 枚举,标识红色       
  8.     BLUE,           ///< 枚举,标志蓝色       
  9.     YELLOW          ///< 枚举,标志×××.       
  10. }enumVar;     

5.5     需要注意的问题

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

6      Doxygen使用的常见问题小结

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

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

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

解决:首先确保安装了graphviz for win,注意不是wingraphviz,后者是一个graphvizcom封装,但是doxygen并不是基于它开发的,所以装了也没用。然后在expertDOT_PATH中填入graphviz的安装路径。接着在wizarddiagram中选择需要生成的图形类别就可以了。
如果出现无法包含.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中定义的类。

7.  感谢

最后,感谢您的阅读,如果您对此有什么建议或者意见,欢迎在本博客上留言,也可以E-mail 至 lujun.hust@gmail.com