doxygen注释语法（三）：一般约定

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

4.1类的函数成员

在头文件的定义处进行简要注释，放在上方：

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;
}

4.2纯虚函数

由于没有实现，则简要注释和详细注释不需分开。

4.3类的数据成员

只在头文件的定义处进行简要注释，不要详细注释。可以在

上方用/** @brief some brief description */

或右方用 ///< some brief description

5、枚举定义

每个枚举定义必须添加注释,格式如下:

/** Another enum, with inline docs */
enum AnotherEnum
{
    V1, ///< value 1
    V2 ///< value 2
};

6、示例

下面是一个简单的例子，完全符合约定：

6.1首先是文件定义

/** @file

* @brief a brief description for the file.

* @author soulmachine

* @date 2008/07/02

* @version 0.1

*

* detailed description for test.cpp

*/

6.2全局函数定义

/** @brief global function, no details

* @note some details about global function*/

void global_test();

6.3类定义

/** @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;
}