Doxygen 是一個程式的檔案産生工具，可将程式中的特定批注轉換成為說明檔案。通常我們在寫程式時，或多或少都會寫上批注，但是對于其它人而言，要直接探索程式裡的批注，與打撈鐵達尼号同樣的辛苦。大部分有用的批注都是屬于針對函式，類别等等的說明。是以，如果能依據程式本身的結構，将批注經過處理重新整理成為一個純粹的參考手冊，對于後面利用您的程式代碼的人而言将會減少許多的負擔。不過，反過來說，整理檔案的工作對于您來說，就是沉重的負擔。
Doxygen 就是在您寫批注時，稍微按照一些它所制訂的規則。接着，他就可以幫您産生出漂亮的文檔了。
是以，Doxygen 的使用可分為兩大部分。首先是特定格式的批注撰寫，第二便是利用Doxygen的工具來産生文檔。
目前Doxygen可處理的程式語言包含：
C/C++
Java
IDL (Corba, Microsoft及KDE-DCOP類型)
而可産生出來的文檔格式有：
HTML
XML
LaTeX
RTF
Unix Man Page
而其中還可衍生出不少其它格式。HTML可以打包成CHM格式，而LaTeX可以透過一些工具産生出PS或是PDF文檔。
1.1 安裝 Doxygen 1.7.4(Windows)
1.2 安裝 graphviz 2.28.0(Windows)
graphviz 是一個由AT&T實驗室啟動的開源工具包，用于繪制DOT語言腳本描述的圖形。Doxygen 使用 graphviz 自動生成類之間和檔案之間的調用關系圖，如不需要此功能可不安裝該工具包。
1.3 安裝 Windows Help Workshop 1.32
Doxygen 使用這個工具可以生成 CHM 格式的文檔。
Doxygen 産生文檔可以分為三個步驟。一是在程式代碼中加上符合Doxygen所定義批注格式。二是使用Doxywizard進行配置。三是使用Doxygen來産生批注文檔。
Doxygen 1.7.4 主界面如下圖 1 所示。
說明：1，Doxygen 工作目錄，就是用來存放配置檔案的目錄。
2，遞歸搜尋源檔案目錄需要選上。
相關配置說明如下圖 2 所示。
相關配置說明如下圖 3 所示。
說明：如果選擇這個選項之前需要先安裝了 Graphviz 工具包。
相關配置說明如下圖 4 所示。
說明：編碼格式，UTF-8 是首選。如果需要顯示中文則選擇GB2313.
TAB_SIZE 主要是幫助檔案中代碼的縮進尺寸，譬如@code和@endcode段中代碼的排版，建議設定成4。
OPTIMIZE_OUTPUT_FOR_C 這個選項選擇後，生成文檔的一些描述性名稱會發生變化，主要是符合C習慣。如果
是純C代碼，建議選擇。
SUBGROUPING這個選項選擇後，輸出将會按類型分組。
Build頁面，這個頁面是生成幫助資訊中比較關鍵的配置頁面：
EXTRACT_ALL 表示：輸出所有的函數，但是private和static函數不屬于其管制。
EXTRACT_PRIVATE 表示：輸出private函數。
EXTRACT_STATIC 表示：輸出static函數。同時還有幾個EXTRACT，相應檢視文檔即可。
HIDE_UNDOC_MEMBERS 表示：那些沒有使用doxygen格式描述的文檔（函數或類等）就不顯示了。當然，如果EXTRACT_ALL被啟用，那麼這個标志其實是被忽略的。
INTERNAL_DOCS 主要指：是否輸出注解中的@internal部分。如果沒有被啟動，那麼注解中所有的@internal部分都
将在目标幫助中不可見。
CASE_SENSE_NAMES 表示：是否關注大小寫名稱，注意，如果開啟了，那麼所有的名稱都将被小寫。對于C/C++這種
字母相關的語言來說，建議永遠不要開啟。
HIDE_SCOPE_NAMES 表示：域隐藏，建議永遠不要開啟。
SHOW_INCLUDE_FILES 表示：是否顯示包含檔案，如果開啟，幫助中會專門生成一個頁面，裡面包含所有包含檔案的列
表。
INLINE_INFO ：如果開啟，那麼在幫助文檔中，inline函數前面會有一個inline修飾詞來标明。
SORT_MEMBER_DOCS ：如果開啟，那麼在幫助文檔清單顯示的時候，函數名稱會排序，否則按照解釋的順序顯
示。
GENERATE_TODOLIST ：是否生成TODOLIST頁面，如果開啟，那麼包含在@todo注解中的内容将會單獨生成并顯
示在一個頁面中，其他的GENERATE選項同。
SHOW_USED_FILES ：是否在函數或類等的幫助中，最下面顯示函數或類的來源檔案。
SHOW_FILES ：是否顯示檔案清單頁面，如果開啟，那麼幫助中會存在一個一個檔案清單索引頁面。
相關配置說明如下圖 5 所示。
說明：輸入的源檔案的編碼，要與源檔案的編碼格式相同。如果源檔案不是UTF-8編碼最好轉一下。
相關配置說明如下圖 6 所示。
說明：1，CHM_FILE檔案名需要加上字尾（xx.chm）。
2，如果在 Wizard 的 Output Topics 中選擇了 prepare for compressed HTML (.chm)選項，此處就會要求選擇 hhc.exe 程式的位置。在 windows help workshop 安裝目錄下可以找到 hhc.exe。
3，為了解決DoxyGen生成的CHM檔案的左邊樹目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312即可。
4，GENERATE_CHI 表示索引檔案是否單獨輸出，建議關閉。否則每次生成兩個檔案，比較麻煩。
5，TOC_EXPAND 表示是否在索引中列舉成員名稱以及分組（譬如函數，枚舉）名稱。
相關配置說明如下圖 7 所示。
點選 Run doxygen 按鈕， Doxygen 就會從源代碼中抓取符合規範的注釋生成你定制的格式的文檔。
并非所有程式代碼中的批注都會被Doxygen 所處理。您必需依照正确的
格式撰寫。原則上，Doxygen 僅處理與程式結構相關的批注，如
Function，Class ，檔案的批注等。對于Function内部的批注則不做
處理。Doxygen可處理下面幾種類型的批注。
JavaDoc類型：
/**
* ... 批注 ...
*/
Qt類型：
/*!
單行型式的批注：
/// ... 批注 ...
或
//! ... 批注 ...
要使用哪種型态完全看自己的喜好。以筆者自己來說，大範圍的注
解我會使用JavaDoc 型的。單行的批注則使用"///" 的類型。
此外，由于Doxygen 對于批注是視為在解釋後面的程式代碼。也就是
說，任何一個批注都是在說明其後的程式代碼。如果要批注前面的程
式碼則需用下面格式的批注符号。
/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...
上面這個方式并不适用于任何地方，隻能用在class 的member或是
function的參數上。
舉例來說，若我們有下面這樣的class。
class MyClass {
public:
int member1 ;
int member2:
void member_function();
};
加上批注後，就變成這樣：
/**
* 我的自訂類别說明 ...
*/
int member1 ; ///< 第一個member說明 ...
int member2: ///< 第二個member說明 ...
int member_function(int a, int b);
* 自訂類别的member_funtion說明 ...
*
* @param a 參數a的說明
* @param b 參數b的說明
* @return 傳回a+b。
*/
int MyClass::member_function( int a, int b )
{
return a+b ;
}
當您使用Doxygen 産生說明文檔時，Doxygen 會幫您parsing 您的程
式碼。并且依據程式結建構立對應的檔案。然後再将您的批注，依據
其位置套入于正确的地方。您可能已經注意到，除了一般文字說明外
，還有一些其它特别的指令，像是@param及@return 等。這正是
Doxygen 另外一個重要的部分，因為一個類别或是函式其實都有固定
幾個要說明的部分。為了讓Doxygen 能夠判斷，所有我們就必需使用
這些指令，來告訴Doxygen 後面的批注是在說明什麼東西。Doxygen
在處理時，就會幫您把這些部分做特别的處理或是排版。甚至是制作
參考連結。
首先，我們先說明在Doxygen 中對于類别或是函數批注的一個特定格
式。
* class或function的簡易說明...
* class或function的詳細說明...
* ...
上面這個例子要說的是，在Doxygen 處理一個class 或是function注
解時，會先判斷第一行為簡易說明。這個簡易說明将一直到空一行的
出現。或是遇到第一個"." 為止。之後的批注将會被視為詳細說明。
兩者的差異在于Doxygen 在某些地方隻會顯示簡易說明，而不顯示詳
細說明。如：class 或function的清單。
另一種比較清楚的方式是指定@brief的指令。這将會明确的告訴
Doxygen，何者是簡易說明。例如：
* @brief class或function的簡易說明...
除了這個class 及function外，Doxygen 也可針對檔案做說明，條件
是該批注需置于檔案的前面。主要也是利用一些指令，通常這部分注
解都會放在檔案的開始地方。如：
/*! \file myfile.h
\brief 檔案簡易說明
詳細說明.
\author 作者資訊
*/
如您所見，檔案批注約略格式如上，請别被"\" 所搞混。其實，"\"
與"@" 都是一樣的，都是告訴Doxygen 後面是一個指令。兩種在
Doxygen 都可使用。筆者自己比較偏好使用"@"。
接着我們來針對一些常用的指令做說明：
@file
檔案的批注說明。
@author
作者的資訊
@brief
用于class 或function的批注中，後面為class 或function的簡易說明。
@param
格式為
@param arg_name 參數說明
主要用于函式說明中，後面接參數的名字，然後再接關于該參數的說明。
@return
後面接函數傳回值的說明。用于function的批注中。說明該函數的傳回值。
@retval
@retval value 傳回值說明
主要用于函式說明中，說明特定傳回值的意義。是以後面要先接一個傳回值。然後在放該傳回值的說明。
Doxygen 所支援的指令很多，有些甚至是關于輸出排版的控制。您可從Doxygen的使用說明中找到詳盡的說明。
下面我們準備一組example.h 及example.cpp 來說明Doxygen 批注的使用方式：
example.h:
* @file 本範例的include檔案。
* 這個檔案隻定義example這個class。
* @author garylee@localhost
#define EXAMPLE_OK 0 ///< 定義EXAMPLE_OK的宏為0。
* @brief Example class的簡易說明
* 本範例說明Example class。
* 這是一個極為簡單的範例。
*
class Example {
private:
int var1 ; ///< 這是一個private的變數
int var2 ; ///< 這是一個public的變數成員。
int var3 ; ///< 這是另一個public的變數成員。
void ExFunc1(void);
int ExFunc2(int a, char b);
char *ExFunc3(char *c) ;
example.cpp:
* @file 本範例的程式代碼檔案。
* 這個檔案用來定義example這個class的
* member function。
* @brief ExFunc1的簡易說明
* ExFunc1沒有任何參數及傳回值。
void Example::ExFunc1(void)
// empty funcion.
* @brief ExFunc2的簡易說明
* ExFunc3()傳回兩個參數相加的值。
* @param a 用來相加的參數。
* @param b 用來相加的參數。
* @return 傳回兩個參數相加的結果。
int ExFunc2(int a, char b)
return (a+b);
* @brief ExFunc3的簡易說明
* ExFunc3()隻傳回參數輸入的名額。
* @param c 傳進的字元指針。
* @retval NULL 空字元串。
* @retval !NULL 非空字元串。
char * ExFunc2(char * c)
return c;
}
本文轉自emouse部落格園部落格，原文連結：http://www.cnblogs.com/emouse/archive/2011/10/25/2224336.html，如需轉載請自行聯系原作者