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 description5、枚举定义
每个枚举定义必须添加注释,格式如下:
/** 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;
}