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 风格的注释风格主要使用下面这种样式：即在注释块开始使用两个星号 ‘ * ‘

/** description
* description
* description
*/

5.3.2 简述与详述的方式

Doxygen 支持的块（类、函数、结构体等）的注释描述分为两种：简述和详述

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

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

/*! @brief Brief description.
* description continued.
*
* Detailed description starts here.
*/

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

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

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

5.3.3 文件头注释示例

5.3.4 类定义注释示例

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

5.3.5 类成员变量定义示例

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

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

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

int m_color; /**< 颜色变量 */

5.3.6 成员函数的注释示例

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

5.3.7 枚举变量的注释示例

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

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 ）使用以空行（或者小数点加空格）作为简述与详述的分割

/// 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 文件头注释示例

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

本文转自 Jhuster 51CTO博客，原文链接：http://blog.51cto.com/ticktick/188674，如需转载请自行联系原作者

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

5 Doxygen的注释风格

5.1 综述

5.2 Doxygen支持的指令

5.2.1 概述

5.2.2 常用指令介绍

5.3 JavaDoc风格的注释

5.3.1 概述

5.3.2 简述与详述的方式

5.3.3 文件头注释示例

5.3.4 类定义注释示例

5.3.5 类成员变量定义示例

5.3.6 成员函数的注释示例

5.3.7 枚举变量的注释示例

5.4 C++风格的注释

5.4.1 概述

5.4.2 简述与详述

5.4.3 注释风格约定

5.4.4 文件头注释示例

5.4.5 类定义注释示例

5.4.6 类成员变量定义示例

5.4.7 成员函数的注释示例

5.4.8 枚举变量的注释示例

5.5 需要注意的问题

6 Doxygen使用的常见问题小结

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

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

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

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

热门文章

最新文章

相关电子书

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

5 Doxygen的注释风格

5.1 综述

5.2 Doxygen支持的指令

5.2.1 概述

5.2.2 常用指令介绍

5.3 JavaDoc风格的注释

5.3.1 概述

5.3.2 简述与详述的方式

5.3.3 文件头注释示例

5.3.4 类定义注释示例

5.3.5 类成员变量定义示例

5.3.6 成员函数的注释示例

5.3.7 枚举变量的注释示例

5.4 C++风格的注释

5.4.1 概述

5.4.2 简述与详述

5.4.3 注释风格约定

5.4.4 文件头注释示例

5.4.5 类定义注释示例

5.4.6 类成员变量定义示例

5.4.7 成员函数的注释示例

5.4.8 枚举变量的注释示例

5.5 需要注意的问题

6 Doxygen使用的常见问题小结

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

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

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

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

热门文章

最新文章

相关电子书

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