Doxygen详细介绍（三）（Doxygen注释风格）

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 非空字符串。
@note	注解
@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.             ……  
9. } 

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     须要注意的问题

（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中定义的类。

 

 

结束语

 

免费学习更多精品课程，登陆乐搏学院官网http://h.learnbo.cn/

或关注咱们的官方微博微信，还有更多惊喜哦~