如果打算使用doxygen为代码产生文档，在编写代码时首先要为代码添加doxygen风格的注释，这些doxygen风格的注释可以称为文档块，添加注释的这个动作可以称为文档化代码。Doxygen会根据相应的doxygen注释块为代码生成相应的文档。
对每个代码条目，doxygen有两种（在某些情况下可以3种）类型的说明，共同组成文档：简要说明和详细说明，对应方法和函数可以有第三种风格的注释，函数体内注释。
简要说明只有一行长，详细说明可以有多行。
注释风格
详细注释可以有如下风格
1、JavaDoc风格的注释，这种风格的注释是在C风格的注释块开始处有两个 “ * “，如下：
/**
* ... 注释块 ...
*/
2、可以采用QT风格的注释，这种风格的注释是在C风格的注释块开始处“ * “后面紧跟”!”，如下：
/*!
* ... 注释块 ...
*/
以上两个例子中 text前的 “ * “ 是可选的，可以写成
/**
... 注释块 ...
*/
和
/*!
... 注释 ...
*/
3、单行注释也可以采用如下方式
///
/// ... 注释 ...
///
或
//!
//!... 注释 ...
//!
4、如下注释也是可以的
/********************************************//**
* ... 注释
***********************************************/
或者
/////////////////////////////////////////////////
/// ...注释...
/////////////////////////////////////////////////
简要说明有如下格式
1、 使用\brief 命令指定简要说明，简要说明以”.” 结束，详细说明在接下来的一个空行后开始，如下：
/*! \brief 简要说明.
* 简要说明续.
*
* 详细说明（上面要留一个空行）.
*/
如果配置文件中把 JAVADOC_AUTOBRIEF 设置成 YES，则可以使用JavaDoc风格注释块, 这种风格的注释，简要说明自动从“*“后开始 ，直到第一个”.”号结束，例如：
/** 简要说明.
* 详细说明.
*/
多行C++风格注释：
/// 简要说明.
/// 详细说明.
3、可以采用如下注释：
/// 简要说明.
/** 详细说明. */
或者
//! 简要说明.
//! 详细 （上面的空行是需要的）
//! 说明.
上例中间空行用来分隔简要说明和详细说明的。请注意下面格式的注释是不合法的，doxygen只允许一条详细说明对应一条简要说明：
//!简洁描述信息
//! 详细描述信息
/*! 注意，又一详细描述信息!
*/
如果一个代码项的声明和定义之前都有简要说明，则doxygen只使用声明之前的说明。
如果一个代码项在声明和定义之前都有详细说明, 则doxygen使用定义之前的说明。
用QT风格注释的C++代码样例
//! A test class.
/*!
A more elaborate class description.
*/
class Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,//! Enum variable.
/*! Details. */
enumVar; //! A constructor.
/*!
A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
};
如果配置文件中JAVADOC_AUTOBRIEF 设置成 YES，可以使用JavaDoc风格注释
/**
* A test class. A more elaborate class description.
*/
class Test
{
public:
/**
* An enum.
* More detailed enum description.
*/
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3 /**< enum value TVal3. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar; /**< enum variable. Details. */
/**
* A constructor.
* A more elaborate description of the constructor.
*/
Test();
/**
* A destructor.
* A more elaborate description of the destructor.
*/
~Test();
/**
* a normal member taking two arguments and returning an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see testMe()
* @param c1 the first argument.
* @param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
/**
* a public variable.
* Details.
*/
int publicVar;
/**
* a function variable.
* Details.
*/
int (*handler)(int a,int b);
};
From:http://www.embstudy.org/home/space.php?uid=8&do=blog&id=66