Doxygen使用简介（4）

四、代码注释规范

为了生成.chm的帮助文档，代码需要按照一定规范进行注释。

doxgen的注释可以分为简要注释和详细注释两种，有3种不同的注释方式，本文选择Qt风格＋’!’的方式作为注释规则。

在要注释的程序前添加：

简要注释：//!  Brief description

详细注释: /*!  Detailed description */

在要注释的程序后添加：

简要注释：//!<  Brief description

详细注释: /*!<  Detailed description */

 *如果注释需要分行显示，可以用’/n’分隔，将’/n’加在行尾。 

4.1 变量注释规则

变量的注释可以放在变量定义前，也可以放正变量定义后。

4.1.1 变量定义前

//! max x position

INT iMaxX = 0;

4.1.2 变量定义后

INT iMaxX = 0; //!< max x position

一般变量后面注释放在同行后面。

4.2 函数及其参数注释规则

函数的注释放在函数内容的前面，其完整的注释包括函数功能描叙、函数参数描述、函数返回值描述、函数错误码描述、函数的补充说明和函数修改记录等6个部分，函数功能描叙放在其简要注释里，其余5个部分放在其详细注释里。

4.2.1 函数声明的注释

函数声明的注释放在函数声明的前面，只包括函数功能描叙，并且要放在简要注释里。

//!Get the value of A

int GetA(){return int m_iA;}

//!后是其功能描叙。

4.2.2 函数实现的注释

函数实现的注释放在函数实现的前面，按序包括函数功能描叙、函数参数描述、函数返回值描述、函数错误码描述、函数修改记录和函数的补充说明等6个部分。函数功能描述注释放在简要注释里，其余部分放在详细注释里。

/*!

@brief get the edge line of  the max blob

@param[in]     iBlobIndex  : int,the blob index

@param[in]     iPtNumThre  : int, the point number threshold

@param[in]  dDistThre : double the distance threshold between the point and the edge line

@param[out] pLeftEdge  : WLine_T*,the left edge line

@param[in,out] pRightEdge  : WLine_T*,the right edge line

@retval TRUE : succeed

@retval FALSE: fail

@date  2009.11.26 j.wu create

*/

BOOL CBaseSample::GetBlobEdge(int iBlobIndex,int iPtNumThre,double        dDistThre,WLine_T *pLeftEdge,WLine_T *pRightEdge)

{

       BOOL bRe = FALSE;

       if((NULL != pLeftEdge)&&(NULL != pRightEdge))

       {

               fnGetBlob(iBlobIndex);

               //............

               bRe = TRUE;

       }

       return bRe;

}

注释说明如下：

(1)如果函数定义部分(.h文件)已有简要注释，则函数实现部分(.c或.cpp)的简要注释在doxygen转换后，不会显示，只显示函数定义的简要注释。函数的详细注释也是一样。

函数的简要注释和详细注释都只能有一个，函数定义部分的注释权限比实现部分的相应注释的高。

(2)参数描叙按照函数的参数顺序进行描叙，@param[in] 后为输入参数名，@param[out]后为输出参数名，对参数的描叙在字符’:’后，先是参数类型，然后是参数功能说明，最后是其它补充说明。

(3) @retval后为函数返回值，’:’后为其说明，不同返回值需要多个@retval命令。

(4)其它格式见例子，注意字符’/n’和空行的位置(space a line)。

4.3 结构体注释规则

//!line : ax + by + c = 0

typedef struct WLine

{

double a;

double b;

double c;

int Length;//!< the length of line

 

WLine()

{

        a = 0;

        b = 0;

        c = 0;

        Length = 0;

}

}WLine_T;

结构体注释如上所示，包括其结构体整体说明和结构体成员变量说明两部分。

4.4 枚举注释规则

//!头的颜色

typedef enum

{

COLOR_INIT_HEAD  = -1, //!< 初始化头部颜色

BLACK_HEAD              = 0,//!< 黑头

WHITE_HEAD             = 1,//!< 白头

}HEAD_COLOR;

枚举注释如上所示，包括其枚举整体说明和枚举变量说明两部分。

4.5 文件注释规则

文件注释放在文件内容的最前面，需要说明文件名、文件功能描述、文件版权和文件修改记录，文件修改记录包括文件修改时间、文件版本号、文件修改人和文件修改原因四部分。具体的注释如下：

头文件：

/*!

@file   BaseSample.h

@brief     base sample class head file

@author  ***.****

@version 1.2

@date      2009.9.1 j.wu create

@date   2009.11.2 j.wu modify for add GetA()

*/

源代码文件:

/*!

@file   BaseSample.cpp

@brief     base sample implementation file

@author EutroVision System Ltd.

@version 1.0

@date      2009.9.1 j.wu create

*/

其中@file、@brief、@author和@date为特殊命令符，@file后为文件名，@brief后为文件功能描叙，@author后为文件版权、@date后为一条文件修改记录。文件修改记录按序由文件修改时间、文件版本号、文件修改人和文件修改原因四部分。文件修改原因如果太长，可以用字符’/n’分行。

4.6 module的注释

有时需要同类的函数或同类的class编成一个组，能够同时出现，可以使用group的命令。

例：

/*!

  /defgroup Sample Sample Block

  @{

*/

class CSampleA   : public CBaseSample

{

public:

CSampleA ( );

virtual ~CSampleA ( );

BOOL Execute(int iRunMode);

};

 

class CSampleB : public CBaseSample 

{

public:

CSampleB( );

virtual ~ CSampleB ( );

BOOL Execute( );

};

/*!

@}

*/

 

/*!

/ingroup Sample

*/

class CSampleC   : public CBaseSample

{

public:

CSampleC ( );

virtual ~CSampleC ( );

BOOL Execute(int iRunMode);

};

 

class CSampleD  : public CSampleD

{

public:

CSampleD( );

virtual ~CSampleD( );

    /*!

/ingroup Sample

*/

BOOL Execute(int iRunMode);

};

这样class CSampleA, class CSampleB, class CSampleC,class CSampleD:: Execute(int iRunMode)就编到一个组Sample中了。

/defgroup后第一个参数为组名标示符，需要具备唯一性，后面的参数是组的显示名称。

/ingroup后面是组名标示符。

   /*! @{ */ 和/*! @} */之间是组包含的内容，这样就不需要在组的每个部分前添加/ingroup了。