C++注释规范.doc

C++注释规范
前言
为了保持程序源码与文档的一致性,提出了源码注释规范化。
文档修订记录
日期
版本
作者
修改内容
2009-6-18

李建生
创建
适用范围
C++
引用文件
doxygen_manual-
术语
概述
根据文档化的源码,直接从源码中抽取文档,保持文档源码一致性。采用开源工具Doxygen,支持输出html、pdf、chm、man手册等。Doxygen支持两种形式的注释:JavaDoc和QT风格,本规范采用通用的JavaDoc形式,更适合一般的编程****惯。
Doxygen安装
Windows平台
直接运行Doxygen 的 Setup EXE文件,依据提示进行安装操作;
运行Graphviz的安装(EXE)文件,依据提示进行安装操作。
Doxygen运行
DOXYFILE_ENCODING=GBK
OUTPUT_LANGUAGE=Chinese
INPUT_ENCODING=GBK
FILE_PATTERNS=*.h *.cpp
RECURSIVE=true
EXTRACT_ALL=TRUE
EXTRACT_PRIVATE=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
Doxygen介绍
如果采用Doxygen为代码产生文档,在编写代码时首先要为代码添加Doxygen风格的注释,这些Doxygen风格的注释可以称为文档块(Document block),添加注释的这个动作可以称为文档化代码。Doxygen会根据相应的doxygen注释块为代码生成相应的文档。
对每个代码条目,Doxygen有两种(在某些情况下可以3种)类型的说明,共同组成文档:简要说明和详细说明。对应方法和函数可以有第三种风格的注释,函数体内注释(in body)。因为没有指定描述顺序,因此不建议多条简要说明或详细说明。
简要说明只有一行,详细说明可以有多行。
以下描述全部以JavaDoc为例。
详细注释
1、JavaDoc风格的注释,这种风格的注释是在C风格的注释块开始处有两个“* “,如下:
/**
* ... 注释块...
*/
上例中文本前的“* “是可选的,也可以写成
/**
... 注释块...
*/
3、单行注释也可以采用如下方式
///
/// ... 注释...
///
4、如下注释也是可以的
/********************************************//**
* ... 注释
***********************************************/
或者
/////////////////////////////////////////////////
/// ...注释...
/////////////////////////////////////////////////
简要注释
如果配置文件中把 JAVADOC_AUTOBRIEF 设置成 YES,则可以使用JavaDoc风格注释块, 这种风格的注释,简要说明自动从“*“后开始,直到第一个”.”号结束,例如:
/** 简要说明.
* 详细说明.
*/
多行C++风格注释:
/// 简要说明.
/// 详细说明.
3、可以采用如下注释:
/// 简要说明.
/** 详细说明. */
上例中间空行用来分隔简要说明和详细说明的。请注意下面格式的注释是不合法的,Doxygen只允许一条详细说明对应一条简要说明:
如果一个代码项的声明和定义之前都有简要说明,则Doxygen只使用声明之前的说明。
如果一个代码项在声明和定义之前都有详细说明, 则Doxygen使用定义之前的说明。
模块注释
定义模块(组)
/*
* ***@defgroup 模块名(具有唯一性) 模块的说明文字
* @{
*/
…定义的内容…
/** @} */ // 模块结尾
增加到组中
在文档块中增加:ingroup 模块名
示例
/** ***@mon lib
* This is the first group
* @{
* @}
*/
/** ***@defgroup base base lib
* ***@mon