C++注释规范 (1)

C++注释规范

前言

为了保持程序源码与文档的一致性，提出了源码注释规范化。文档修订记录

1适用范围

C++

2引用文件

doxygen_manual-1.5.9.pdf

3术语

4概述

根据文档化的源码，直接从源码中抽取文档，保持文档源码一致性。采用开源工具Doxygen，支持输出html、pdf、chm、man手册等。Doxygen支持两种形式的注释：JavaDoc 和QT风格，本规范采用通用的JavaDoc形式，更适合一般的编程习惯。

5Doxygen安装

5.1 Windows平台

✓直接运行Doxygen 的Setup EXE文件，依据提示进行安装操作；

✓运行Graphviz的安装（EXE）文件，依据提示进行安装操作。

6Doxygen运行

DOXYFILE_ENCODING=GBK

OUTPUT_LANGUAGE=Chinese

INPUT_ENCODING=GBK

FILE_PATTERNS=*.h *.cpp

RECURSIVE=true

EXTRACT_ALL=TRUE

EXTRACT_PRIVA TE=TRUE

EXTRACT_STATIC=TRUE

EXTRACT_LOCAL_CLASSES=TRUE

EXTRACT_LOCAL_METHODS=TRUE

SHOW_INCLUDE_FILES=TRUE

INLINE_INFO=TRUE

SHOW_DIRECTORIES=TRUE

SHOW_FILES=TRUE

SHOW_NAMESPACE=TRUE

7Doxygen介绍

如果采用Doxygen为代码产生文档，在编写代码时首先要为代码添加Doxygen风格的注释，这些Doxygen风格的注释可以称为文档块(Document block)，添加注释的这个动作可以称为文档化代码。Doxygen会根据相应的doxygen注释块为代码生成相应的文档。

对每个代码条目，Doxygen有两种（在某些情况下可以3种）类型的说明，共同组成文档：简要说明和详细说明。对应方法和函数可以有第三种风格的注释，函数体内注释（in body）。因为没有指定描述顺序，因此不建议多条简要说明或详细说明。

简要说明只有一行，详细说明可以有多行。

以下描述全部以JavaDoc为例。

7.1 详细注释

1、JavaDoc风格的注释，这种风格的注释是在C风格的注释块开始处有两个“* “，如下：

/**

* ... 注释块...

*/

上例中文本前的“* “是可选的，也可以写成

/**

... 注释块...

*/

3、单行注释也可以采用如下方式

///

/// ... 注释...

///

4、如下注释也是可以的

/********************************************//**

* ... 注释

***********************************************/

或者

/////////////////////////////////////////////////

/// ...注释...

/////////////////////////////////////////////////

7.2 简要注释

如果配置文件中把JA V ADOC_AUTOBRIEF 设置成YES，则可以使用JavaDoc风格注释块, 这种风格的注释，简要说明自动从“*“后开始，直到第一个”.”号结束，例如：

/** 简要说明.

* 详细说明.

*/

多行C++风格注释：

/// 简要说明.

/// 详细说明.

3、可以采用如下注释：

/// 简要说明.

/** 详细说明. */

上例中间空行用来分隔简要说明和详细说明的。请注意下面格式的注释是不合法的，Doxygen只允许一条详细说明对应一条简要说明：

如果一个代码项的声明和定义之前都有简要说明，则Doxygen只使用声明之前的说明。

如果一个代码项在声明和定义之前都有详细说明, 则Doxygen使用定义之前的说明。

7.3 模块注释

7.3.1定义模块（组）

/*

* @defgroup 模块名（具有唯一性）模块的说明文字

* @{

*/

…定义的内容…

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

7.3.2增加到组中

在文档块中增加:ingroup 模块名

7.3.3示例

/** @defgroup common common lib

* This is the first group

* @{

* @}

*/

/** @defgroup base base lib

* @ingroup common

*/

7.4 成员分组

如果一个组合结构（如类、文件）有很多成员，则可能需要对这些成员进行分组。Doxygen 会根据类型和保护方式自动进行分组。成员分组不能嵌套。

/*

* @name 分组说明文字

* @{

*/

…定义的内容…