C++代码注释详解

常用注释语法

• 注释写在对应的函数或变量前面。JavaDoc类型的多行注释风格如下：

/**
* 这里为注释.
*/

• 一般注释中有简要注释和详细注释，简要注释有多种标识方式，这里推荐使用@brief命令强制说明，例如：
  

/**
* @brief 这里为简要注释.
*
* 这里为详细注释.
*/

• @brief之后为简要注释，简要注释结束的标志是一个点号，或一个空行。简要注释之后的注释为详细注释，因此也可以写成：其中\n为换行符。

/**
* @brief 简要注释. 详细注释. \n
* 这里仍然为详细注释.
*/

• 下面对几种注释类型进行描述。

文件头注释

• 一般@file后为空，Doxygen会默认为是@file所在文件的文件名。[]表示可选，{}表示重复0到N次，<>表示必须参数，@author表示作者，@data表示日期，@version表示版本号。

/** 
* @file [file-name]
* @brief brief description for the file.
* @author <list of authors>
* {@author <list of authors>}
* [@author <authors description>]
* @date <date>
* @version <version number>
*
* detailed description for the file.
*/

类注释

• header-file是类声明所在的头文件名字，header-name是要显示的链接文字，一般为头文件的真实路径。

/**
* @class <class-name> [header-file] [header-name]
* @brief brief description for the class.
*
* detailed description for the class.
*/

函数注释

/**
* @brief brief description.
* {@param <parameter-name> <parameter description>}
* @exception <exception-object> <exception description>
* {@exception <exception-object> <exception description>}
* @return <description of the return value>
* {@return <description of the return value>}
* @note <text>
* @remarks <remark text>
* {@remarks <remark text>}
* [@deprecated <description>]
* [@since when(time or version)]
* [@see references{,references}]
*/

@param	参数名及其解释（param后加[in]表示输入参数，param后加[out]表示输出参数）
@exception	用来说明异常类及抛出条件
@return	对函数返回值做解释
@note	表示注解，暴露给源码阅读者的文档
@remark	表示评论，暴露给客户程序员的文档
@since	表示从那个版本起开始有了这个函数
@deprecated	引起不推荐使用的警告
@see	表示交叉参考

 成员注释

• /**<用来注释成员，放在成员后面，格式如下：

int var; /**< Detailed description after the member */

• 此语法对成员函数也适用。对于枚举类型也可采用这种注释，如下：

/** @brief Another enum, with inline docs */
enum AnotherEnum
{
    V1,   /**< value 1 */
    V2    /**< value 2 */
};

项目符号标记注释

 /**
* A list of events:
* - mouse events
* -# mouse move event
* -# mouse click event\n
*/

结果为：

A list of events:

。mouse events
  mouse move event
  mouse click event

分组注释

• 对于某几个功能类似的代码项（比如类、函数、变量）等，如果希望一起添加注释，而又不想提升到模块的概念，可以通过下面的方式：

/**
* @name 组名 组的说明文字
* @brief 组的简要注释.
* 
* 组的详细注释.
* @{
*/

• 组内的代码;
• 在一页内分组显示。其中组名组名的命名符合c++命名规范。

/** @} */ //组结尾

 模块注释

• 进行设计时，通常有模块的概念，一个模块可能有多个类或者函数组成，完成某个特定功能的代码的集合。生成的模块的注释会单独放在一个模块的页面中。使用下面的格式定义一个模块：

/**
* @defgroup 模块名 模块的说明文字
* @brief模块的简要注释.
*
* 模块的详细注释.
* @{
*/

代码;

/** @} */ // 模块结尾

• 其中模块名Module-Name的命名符合c++命名规范。
• 任何其他代码项（比如类、函数、甚至文件）如果要加入到某个模块，使用ingroup命令即可。模块之间使用ingroup命令，可以组成树状关系。例如要把文件util.cpp加入到模块module_A中，格式如下：

/** 
* @file util.cpp 
* @ingroup module_A
* @brief brief description of the module.
*
* detailed description of the module.
* @
*/

• 同样，对于类和命名空间都可以加入到某模块中，所不同的是把@file util.cpp换成对应的@class class-name和@namespace namespace-name。
• 把多个代码项一起添加到某个模块中可以使用addtogroup命令，格式和defgroup类似，如下：

/**
* @addtogroup模块名
* @{
*/