程序注释格式
编写正确格式的注释说明
头文件头部注释规范,注释必须列出版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等,头文件的注释中还应有函数功能简要说明:
/
/// Copyright (C), 2005-2007.
/// file WindowsNT
/// brief Windows Nice Try.
/// author Bill Gates
/// author Several species of small furry animals gathered together
/// in a cave and grooving with a pict.
/// version 4.0
/// date 1996-1998
/// warning This class may explode in your face.
/// warning If you inherit anything from this class, you're doomed.
/// ClassList:主要函数列表,每条记录应包括函数名及功能简要说明
/// 1. ....
/// History: 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述
///
<author> <time> <version > <desc>
///
Hsz 2005/4/12 1.0 build this moudle
源文件头部注释规范,列出:版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及其功能、修改日志等。示例:下面这段源文件的头注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内:
/
/// Copyright (C), 2005-2007,
/// /file WindowsNT
/// /brief Windows Nice Try.
/// /author Bill Gates
/// /author Several species of small furry animals gathered together
/// in a cave and grooving with a pict.
/// /version 4.0
/// /date 1996-1998
/// /warning This class may explode in your face.
/// /warning If you inherit anything from this class, you're doomed.
/// /Function List:主要函数列表,每条记录应包括函数名及功能简要说明
/// 1. ....
/// /History: 修改历史记录列表,每条修改记录应包括修改日期、修改者及修改内容简述
///
<author> <time> <version > <desc>
///
Hsz 2005/4/12 1.0 build this moudle
/
函数头部注释规范,列出:函数的目的/功能、输入参数、输出参数、返回值、调用关系(函数、表)等。示例:下面这段函数的注释比较标准,当然,并不局限于此格式,但上述信息建议要包含在内:
/
/// /fn 函数名称
/// /brief 函数功能、性能等的描述.
/// /param[in] 参数 c a char.
/// /param[out] 参数 n an int.
/// /exception 异常 std::out_of_range parameter is out of range.
/// /return 返回值 a char pointer.
/
类的头部注释规范:
/
/// /class 类名字 类所在文件 "文件路径"
/// /brief 大纲描述.
///
/// 详细描述类的功能
/
类成员定义的注释规范:
成员函数
/// A function.
/// A more elaborate description of the constructor.
成员变量
///< a public variable. Details
标准类型的注释规范:
Enum
第一种方法
//
/// /enum TEnum
/// A description of the enum type.
//
enum TEnum {
Val1, /// /var Enum Val1
Val2 /// Enum Val2
};
第二种方法
enum在类内部定义
//
/// /enum An enum
/// More detailed enum description..
//
enum TEnum {
TVal1, ///< enum value TVal1.
TVal2, ///< enum value TVal2.
TVal3 ///< enum value TVal3.
}
*enumPtr, ///< enum pointer. Details.
enumVar; ///< enum variable. Details.
#define
macro宏定义
//
/// /def MAX(x,y)
/// Computes the maximum of /a x and /a y.
//
typedef类型定义
//
/// /typedef std::string YString
/// typedef YString.
//
Struct结构
//
///
/struct Test struct.h "inc/ struct.h"
///
/brief This is a test struct.
///
Some details about the Test struct
///
变量定义
///
/// /var int g_nCount
/// The description of the int value.
///