（轉自：http://www.cnblogs.com/liuliunumberone/archive/2012/04/10/2441391.html）

一．什么是Doxygen?

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文檔。

二．安裝Doxygen

1.1?安裝 Doxygen 1.7.4(Windows)　　?　　http://sourceforge.net/projects/doxygen/?
1.2?安裝 graphviz 2.28.0(Windows) ? ??　　http://www.graphviz.org/Download

graphviz?是一個由AT&T實驗室啟動的開源工具包，用于繪制DOT語言腳本描述的圖形。Doxygen?使用 graphviz 自動生成類之間和文件之間的調用關系圖，如不需要此功能可不安裝該工具包。

1.3?安裝 Windows Help Workshop 1.32

Doxygen?使用這個工具可以生成 CHM 格式的文檔。

三．Doxygen的配置

Doxygen?產生文檔可以分為三個步驟。一是在程序代碼中加上符合Doxygen所定義批注格式。二是使用Doxywizard進行配置。三是使用Doxygen來產生批注文檔。
Doxygen 1.7.4?主界面如下圖?1?所示。

?說明：1，Doxygen?工作目錄，就是用來存放配置文件的目錄。

?????? 2，遞歸搜索源文件目錄需要選上。

選擇?wizard?標簽下的?Output Topics

相關配置說明如下圖?2?所示。

?選擇?wizard?標簽下的?Diagrams Topics

相關配置說明如下圖?3?所示。

說明：如果選擇這個選項之前需要先安裝了?Graphviz?工具包。

選擇?expert?標簽下的?Project Topics

相關配置說明如下圖?4?所示。

說明：編碼格式，UTF-8?是首選。如果需要顯示中文則選擇GB2313.

TAB_SIZE?主要是幫助文件中代碼的縮進尺寸，譬如@code和@endcode段中代碼的排版，建議設置成4。

OPTIMIZE_OUTPUT_FOR_C?這個選項選擇后，生成文檔的一些描述性名稱會發生變化，主要是符合C習慣。如果

是純C代碼，建議選擇。

SUBGROUPING這個選項選擇后，輸出將會按類型分組。

選擇?expert?標簽下的?Build

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?：是否顯示文件列表頁面，如果開啟，那么幫助中會存在一個一個文件列表索引頁面。

選擇?expert?標簽下的?Input Topics

相關配置說明如下圖?5?所示。

說明：輸入的源文件的編碼，要與源文件的編碼格式相同。如果源文件不是UTF-8編碼最好轉一下。

選擇?expert?標簽下的?HTML Topics

相關配置說明如下圖?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?表示是否在索引中列舉成員名稱以及分組（譬如函數，枚舉）名稱。

選擇?Run?標簽

相關配置說明如下圖?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();
??? };
????
加上批注后，就變成這樣：

??? /**
???? * 我的自訂類別說明 ...
???? */
??? class MyClass {
??????? public:
??????????? 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的詳細說明...
???? * ...
???? */

除了這個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的變數
??????? public:
??????????? 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。
???? *
???? * @author garylee@localhost
???? */
????
??? /**
???? * @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;
??? }????