簡介Doxygen

一．什麼是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) 

· 1.2 安裝 graphviz 2.28.0(Windows)

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 是首選。如果需要顯示中文則選擇GB2312.

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編碼最好轉一下。

總結：

我檢視到我的程式碼檔案是GB2312的（檢視方法（以VS2008為例）：檔案->高階儲存選項)。此時如果這裡還是選擇UTF-8，那麼會導致編譯出來的CHM檔案中的中文會有亂碼。

選擇 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 [email protected]      */                  #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 [email protected]      */          /**      * @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;     }