如果打算使用doxygen為代碼產(chǎn)生文檔，在編寫(xiě)代碼時(shí)首先要為代碼添加doxygen風(fēng)格的注釋?zhuān)@些doxygen風(fēng)格的注釋可以稱(chēng)為文檔塊，添加注釋的這個(gè)動(dòng)作可以稱(chēng)為文檔化代碼。Doxygen會(huì)根據(jù)相應(yīng)的doxygen注釋塊為代碼生成相應(yīng)的文檔。
對(duì)每個(gè)代碼條目，doxygen有兩種（在某些情況下可以3種）類(lèi)型的說(shuō)明，共同組成文檔：簡(jiǎn)要說(shuō)明和詳細(xì)說(shuō)明，對(duì)應(yīng)方法和函數(shù)可以有第三種風(fēng)格的注釋?zhuān)瘮?shù)體內(nèi)注釋。
簡(jiǎn)要說(shuō)明只有一行長(zhǎng)，詳細(xì)說(shuō)明可以有多行。
注釋風(fēng)格
詳細(xì)注釋可以有如下風(fēng)格
1、JavaDoc風(fēng)格的注釋?zhuān)@種風(fēng)格的注釋是在C風(fēng)格的注釋塊開(kāi)始處有兩個(gè) “ * “，如下：
/**
* ... 注釋塊 ...
*/
2、可以采用QT風(fēng)格的注釋?zhuān)@種風(fēng)格的注釋是在C風(fēng)格的注釋塊開(kāi)始處“ * “后面緊跟”!”，如下：
/*!
* ... 注釋塊 ...
*/
以上兩個(gè)例子中 text前的 “ * “ 是可選的，可以寫(xiě)成
/**
... 注釋塊 ...
*/
和
/*!
... 注釋 ...
*/
3、單行注釋也可以采用如下方式
///
/// ... 注釋 ...
///
或
//!
//!... 注釋 ...
//!
4、如下注釋也是可以的
/********************************************//**
* ... 注釋
***********************************************/
或者
/////////////////////////////////////////////////
/// ...注釋...
/////////////////////////////////////////////////
簡(jiǎn)要說(shuō)明有如下格式
1、 使用\brief 命令指定簡(jiǎn)要說(shuō)明，簡(jiǎn)要說(shuō)明以”.” 結(jié)束，詳細(xì)說(shuō)明在接下來(lái)的一個(gè)空行后開(kāi)始，如下：
/*! \brief 簡(jiǎn)要說(shuō)明.
* 簡(jiǎn)要說(shuō)明續(xù).
*
* 詳細(xì)說(shuō)明（上面要留一個(gè)空行）.
*/
如果配置文件中把 JAVADOC_AUTOBRIEF 設(shè)置成 YES，則可以使用JavaDoc風(fēng)格注釋塊, 這種風(fēng)格的注釋?zhuān)?jiǎn)要說(shuō)明自動(dòng)從“*“后開(kāi)始 ，直到第一個(gè)”.”號(hào)結(jié)束，例如：
/** 簡(jiǎn)要說(shuō)明.
* 詳細(xì)說(shuō)明.
*/
多行C++風(fēng)格注釋?zhuān)?br>
/// 簡(jiǎn)要說(shuō)明.
/// 詳細(xì)說(shuō)明.
3、可以采用如下注釋?zhuān)?br>
/// 簡(jiǎn)要說(shuō)明.
/** 詳細(xì)說(shuō)明. */
或者
//! 簡(jiǎn)要說(shuō)明.
//! 詳細(xì) （上面的空行是需要的）
//! 說(shuō)明.
上例中間空行用來(lái)分隔簡(jiǎn)要說(shuō)明和詳細(xì)說(shuō)明的。請(qǐng)注意下面格式的注釋是不合法的，doxygen只允許一條詳細(xì)說(shuō)明對(duì)應(yīng)一條簡(jiǎn)要說(shuō)明：
//!簡(jiǎn)潔描述信息
//! 詳細(xì)描述信息
/*! 注意，又一詳細(xì)描述信息!
*/
如果一個(gè)代碼項(xiàng)的聲明和定義之前都有簡(jiǎn)要說(shuō)明，則doxygen只使用聲明之前的說(shuō)明。
如果一個(gè)代碼項(xiàng)在聲明和定義之前都有詳細(xì)說(shuō)明, 則doxygen使用定義之前的說(shuō)明。
用QT風(fēng)格注釋的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 設(shè)置成 YES，可以使用JavaDoc風(fēng)格注釋
/**
* 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