doxygen常用注释语法.doc

2.常用注释语法  
注释写在对应的函数或变量前面。  
 简要注释和详细注释：  
/**  
*  @brief  Brief  Description.  
 *  
 *  Detailed  Description  
 */  
简要注释遇到一个空行或新的命令会结束，后面的就表示是详细注释。  
 JavaDoc风格下，自动会把第一个句号前的文本作为简要注释，后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF设为YES。  
 为了注释一个类中的member，首先要对该类作注释。同样的问题上升到namespace。要注释一个全局的function，typedef，enum或preprocessor定义，你需要首先定义（只能用@file，因为文件不再任何东西里面，就只能用特殊命令实现了，而不像类、函数等，既可以在上方放注释，也可以用@class、@fn进行注释）包含它的文件。  

（1）文件头注释  
/**  @file  [file‐name]  
 *@brief  brief  description  
*  @author  <list  of  authors>  
 *  [@author  <authors  description>]  
 *  @date  <date>  
 *  @version  <version  number>  
 *  @note  
 *  detailed  description  
*/  
 一般@file后我们空着，Doxygen会默认为是@file所在文件的文件名。  
 []表示可选，{}表示重复0到N次，<>表示必须参数。@author  表示作者，@data表示日期，@version表示版本号。
 （2）类注释  
/**  
 *  @class  <class‐name>  [header‐file]  [header‐name]  
 *  @brief  brief  description  
*  @author  <list  of  authors>  
 *  @note  
 *  detailed  description  
*/  
header‐file是类声明所在的头文件名字，header‐name是要显示的链接文字，一般为头文件的真实路径。  
（3）函数注释  
/**  
 *  @brief  brief  description  
*  @author  <list  of  authors>  
 *  {@param[in|out]  <parameter‐name>  <parameter  description>}  
 *  @exception  <exception‐object>  <exception  description>  
 *  {@exception  <exception‐object>  <exception  description>}  
 *  @return  <description  of  the  return  value>  
 *  {@return  <description  of  the  return  value>}  
 *  @note  
 *  detailed  description  
*  @remarks  <remark  text>  
 *  {@remarks  <remark  text>}  
 *  [@deprecated  <description>]  
 *  [@since  when(time  or  version)]  
 *  [@see  references{,references}]  
 */  
@可用\代替，但我倾向于用@。  
@param[in|out]   参数名及其解释  
@exception  用来说明异常类及抛出条件  
@return   对函数返回值做解释  
@note   表示注解，暴露给源码阅读者的文档  
@remark   表示评论，暴露给客户程序员的文档  
@since   表示从那个版本起开始有了这个函数  
@deprecated  引起不推荐使用的警告  
@see   表示交叉参考  
函数的详细注释用@note代替详细注释，因为详细注释要空行隔开，容易忘记。
（4）成员注释  
/**<  或//<用来注释成员，放在成员后面，格式如下：  
int  var;  /**<  Detailed  description  after  the  member  */  
int  var;  ///<  Brief  description  after  the  member  
此语法对函数成员也适用。  
 （5）枚举类型注释  
      /**  @brief  Another  enum,  with  inline  docs  */
enum  AnotherEnum  
      {  
        V1,  /**<  value  1  */  
        V2   /**<  value  2  */  
      };  

一般约定：  
 （1）每个.h和.cpp文件的头部，必须要有简要注释和详细注释，习惯用法如下：  
/**  @file  
 *@brief  brief  description  
*  @author  <list  of  authors>  
*  @date  <date>  
 *  @version  <version  number>  
*  @note  
 *  detailed  description  
*/
（2）每个类的声明上方，必须要有简要注释和详细注释，习惯用法如下：  
/**  
 *  @class  
 *  @brief  brief  description  
*  @author  <list  of  authors>  
*  @note  
 *  detailed  description  
*/  
 （3）全局变量和全局宏必须要有注释。  
如果注释较短，则可以在上方用  
/**  @brief  some  brief  description  */或右方用  
///<  some  brief  description。  
进行简要注释。  
 （4）任何函数都必须要有简要注释和详细注释，习惯用法如下：  
/**  
 *  @brief  brief  description  
*  @author  <list  of  authors>  
 *  @param[in|out]  <parameter‐name>  <parameter  description>  
 *  @exception  <exception‐object>  <exception  description>  
*  @return  <description  of  the  return  value>  
*  @note  
 *  detailed  description  
*  @remarks  <remark  text>  
*/  
对于类的函数成员，在头文件的定义处进行简要注释，放在上方：  
class  Test  
{  
public:
/**  @brief  brief  description  */  
 int  m_test(int  a);  
}  
而在实现出给出详细注释：  
/**  
*  @author  <list  of  authors>  
 *  @param  [in|out]  <parameter‐name>  <parameter  description>  
 *  @exception  <exception‐object>  <exception  description>  
*  @return  <description  of  the  return  value>  
*  @note  
 *  detailed  description  
*  @remarks  <remark  text>  
*/  
int  Test::m_test(int  a)  
{  
 Return  0;  
}  
纯虚函数由于没有实现则简要注释和详细注释不需分开。  
 对于类的数据成员，只在头文件的定义处进行简要注释，不要详细注释。可以在上方用/**  @brief  some  brief  description  */或右方用///<  some  brief  description。  
 （5）每个枚举定义必须添加注释,格式如下:  
/**  Another  enum,  with  inline  docs  */  
enum  AnotherEnum  
{  
V1,  //<  value  1  
V2   //<  value  2  
};  
下面是一个简单的例子，完全符合约定：  
/** @file
* @brief a brief description for the file.
* @author soulmachine
* @date 2008/07/02
* @version 0.1
*
* detailed description for test.cpp
*/
/** @brief global function, no details
* @note some details about global function
*/
void global_test();
/** @class Test test.h "inc/test.h"
* @brief A test class.

*
* A more elaborate class description.
*/
class Test
{
public:
/** @brief A enum, with inline docs */
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
//这里Doxygen对enumPtr的处理有点问题
*enumPtr, ///< enum pointer.
enumVar; ///< enum variable.
/** @brief A constructor. */
Test();
/** @brief A destructor. */
~Test();
/** @brief a normal member taking two arguments and returning an integer value. */
int testMe(int a,const char *s);
/** @brief A pure virtual member.
* @param[in] c1 the first argument.
* @param[in] c2 the second argument.
* @see testMe()
*/
virtual void testMeToo(char c1,char c2) = 0;
int publicVar;//< a public variable.
/** @brief a function variable, note Details. */
int (*handler)(int a,int b);
/** @brief brief before delaration */
int m_func(int a);
};
/** A more elaborate description of the constructor. */

Test::Test()
{
}
/** A more elaborate description of the destructor. */
Test::~Test()
{
}
/**
* @param[in] a an integer argument.
* @param[in] s a constant character pointer.
* @return The test results
* @note Details.
* @par
* Another detail.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
*/
int Test::testMe(int a,const char *s)
{
return 0;
}
/**
* @param[in] a a interger
* @return 0
* @note detailed description
* @remarks remarks,important
* @since 1.0
* @see testMeToo
*/
int Test::m_func(int a)
{
return 0;
}