程序注释格式

程序注释格式

                                      

 

编写正确格式的注释说明

头文件头部注释规范，注释必须列出版权说明、版本号、生成日期、作者、内容、功能、与其它文件的关系、修改日志等，头文件的注释中还应有函数功能简要说明：

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

/// 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.

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