doxygen教程之注释风格

作者：朱金灿

  doxygen是一个开源的C++接口文档生成工具。要使用doxygen生成接口文档，就必须遵循它的注释规范，下面对它的注释规范进行简单介绍。
1.JavaDoc风格注释：

/**
* your comment text.
*/

2.Qt风格:

/*!
* your comment text.
*/

3.仿c++风格:

///                               //!
/// your comment text.      或者: //! your comment text.
///                               //!

要使用哪种型态完全看自己的喜好。
  此外，由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说，任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。

/*!< … 批注 … *//**< … 批注 … *///!< … 批注 …///< … 批注 …

  上面这个方式并不适用于任何地方，只能用在class 的member或是function的参数上。
一、文件注释，放于文件的开头：

/**
* @file           filename
* @brief        This is a brief description.
* @details     This is the detail description.
* @author    author
* @date        date
* @version    A001
* @par Copyright (c): 
*         XXX公司
* @par History:         
*    version: author, date, desc

*/

二、class的注释：

namespace MySPace
{   
class MyClass
   {      
 public:           
 int member1 ;          
 int member2:           
 void member_function();   
 };
}

加上批注后，就变成这样：

namespac MySPace{
/**     @class 
* @brief 我的测试类
   *
   *   用来处理什么的逻辑
   *  @author ycj
   *  @version 0.1
   *  @date    13.09.02 
   */
class MyClass
   {
public:          
int member1;     ///< 第一个member说明 …           
int member2;    ///< 第二个member说明 …          
int member_function(int a, int b);   };
}

using namespace MySPace;
/**    
* @brief 自定义类别的member_funtion说明…
* @param[in] int a 参数a的说明    
* @param[out] int b 参数b的说明  
* @return 传回a+b
*/ 
int MyClass::member_function( int a, int b )   
{      
return a+b ;   
}

三、数据结构注释，放于数据结构定义前:

/**
* The brief description.
* The detail description.
*/
typedef struct
{
   int var1;///<Description of the member variable
}XXXX;

四、宏定义注释，放于宏定义上方或者右侧:

/** Description of the macro */
#define XXXX_XXX_XX        0

或者：

#define XXXX_XXX_XX  0 ///< Description of the macro.

五、全局和静态变量注释：

/**  Description of global variable  */
int g_xxx = 0;
static int s_xxx = 0;///<  Description of static variable

六、枚举类型注释：

/// 界面语言版本
enum UILanguageType
{
    LANGUAGE_ENGLISH, ///< 英文
    LANGUAGE_CHINESE  ///< 中文
};

以上例子仅供参考。