如果打算使用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