Doxygen注释风格

内容参见http://blog.51cto.com/ticktick/188674

https://blog.csdn.net/czyt1988/article/details/8901191

1      Doxygen的注释风格

1.1   综述

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是 brief描述, 另一种就是 detailed。 两种都是可选的，但不能同时没有。

顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。

Doxygen支持c、c++风格注释以及javaDoc风格注释等。

若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：
    1） 文件头（包括.h和.cpp）
        主要用于声明版权，描述本文件实现的功能，以及版本信息等
    2） 类定义
        主要用于描述类功能，同时也可以包含使用方法或者注意事项的简要描述
    3） 类成员变量定义
        在类成员变量上方，对该成员变量进行简要地描述
    4） 类的成员函数定义
        在类定义的成员函数上方，对该成员函数功能进行简要描述
    5） 函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等

1.2    Doxygen支持的指令

1.2.1   概述

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

1.2.2   常用指令介绍

@file	档案的批注说明。
@author	作者的信息
@brief	用于class 或function的简易说明，通常在一行内完事儿 eg ： @brief  本函数负责打印错误信息串 使用以空行（或者小数点加空格）作为简述与详述的分割 1、使用空行分割简述与详述 ///   Brief description    ///   description continued.    ///       ///   Detailed description starts here.   2、以小数点加空格作为分隔如下： ///         Brief description   ///         description continued . （注意:这里有一个小数点,加上一个空格）   ///         Detailed description starts here.   ///
@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 本函数执行可能会产生超出范围的异常

 

1.3      注释风格的分类描述

1.3.1    文件头说明

文件头说明按照如下格式写

/*!
* \file Ctext.h
* \brief 概述 
* 
*详细概述 
* 
* \author 作者,包含email等 
* \version 版本号(maj.min，主版本.分版本格式) 
* \date 日期 
*/

上注释等下于下面这种写法

/*!
 \file Ctext.h
\brief 概述 
详细概述 
\author 作者,包含email等 
\version 版本号(maj.min，主版本.分版本格式) 
\date 日期 
*/

对于vs编译器可能中间那行*号比较麻烦，可以不写，对于Qt这种要去掉中间的*号反而是件麻烦事就不用去掉
用doxygen生成注释如下效果

1.3.2    命名空间

命名空间说明如下写

// \brief 命名空间的简单概述 
/// 
///命名空间的详细概述
namespace text
{
 
}

生成的doxygen效果如下

1.3.3    类说明

类的注释类似命名空间

/// \brief Ctext的doxygen测试
///
/// 作doxygen测试用
class Ctext
{
}

生成的doxygen效果如下

1.3.4    函数

1.3.4.1详细注释样式

函数最好采用详细注释，这里只给出详细注释的样式

/// \brief 函数简要说明-测试函数
/// 
/// 函数详细说明，这里写函数的详细说明信息，说明可以换行
/// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行
/// ，详细说明之前不需要任何标识符
/// \param n1 参数1说明
/// \param c2 参数2说明
/// \return 返回说明
bool text2(int n1,Ctext c2);

生成的效果如下：

1.3.4.2 带参见的注释方式

/// \brief 函数说明-测试函数4
/// \param n1 参数1说明
/// \param c2 参数2说明
/// \return 返回说明
/// \see text3 text2 text
bool text4(int n1,Ctext c2);

生成效果如下：

\see 上可以带中文等说明，doxygen会自动识别代码里存在的函数

1.3.5 变量注释

变量注释用///< 对变量进行说明，对于详细信息可以加\brief

int m_a;     ///< 成员变量1m_a说明
double m_b; ///< 成员变量2m_b说明
 
/// \brief 成员变量m_c简要说明
///
/// 成员变量m_c的详细说明，这里可以对变量进行
///详细的说明和描述，具体方法和函数的标注是一样的
float m_c;

如果变量需要详细说明的可已按照m_c的写法写，注意，m_b和m_c之间一定需要空行，否则会导致m_b的简述消失
上注释用doxygen生成文档的具体效果如下

1.3.6枚举

枚举变量的标注如下：

/// \brief xxx枚举变量的简要说明
///
/// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明
///的写法是一致的。每个枚举变量下可以进行单独说明
enum{
    em_1,///< 枚举值1的说明
    em_2,///< 枚举值2的说明
    em_3 ///< 枚举值3的说明
};

枚举的总体说明和函数的写法一致，每个枚举变量的说明和变量的说明写法一致
上注释用doxygen生成效果如下：