Doxygen簡介及使用說明
一、 Doxygen簡介
Doxygen是一個程式的文件產生工具，可以將程式中的註釋轉換成說明文件或者說是API參考手冊，從而減少程式設計師整理文件的時間。當然這裡程式中的註釋需要遵循一定的規則書寫，才能讓Doxygen識別和轉化。
目前Doxygen可處理的程式語言包含C/C++、Java、Objective-C、IDL等，可產生出來的文件格式有HTML、XML、LaTeX、RTF等，此外還可衍生出不少其它格式，如HTML可以打包成CHM格式，而LaTeX可以通過一些工具產生出PS或是PDF文件等。
二、 下載及安裝
Windows平臺下，下載完成後，直接按照對話方塊提示安裝即可。
Linux平臺下，下載完成後，輸入：
./configure
Make install
可執行的二進位制檔案將被安裝到<prefix>/bin 目錄下。<prefix>預設路徑為/usr/local，可使用配置指令碼的--prefix選項來修改安裝的預設路徑。
另外，也可以安裝一些輔助工具來生成更加漂亮的文件。如可以使用graphviz中的dot工具來渲染出效果更好的圖表，因此，如果需要在註釋中加入圖表可以下載並安裝GraphViz(http://www.graphviz.org/Download..php)； Windows平臺下還可以安裝 Windows Help Workshop來生成 CHM 格式的文件等等。
三、 程式碼的註釋格式
並非所有程式程式碼中的註釋都會被Doxygen所處理，而是必須依照正確的格式撰寫。原則上，Doxygen僅處理與程式結構相關的註釋，如Function，Class等。對於Function內部的註釋則不做處理。Doxygen可處理下面幾種型別的註釋。
JavaDoc型別：
/*
* ... 註釋 ...
*/Qt型別的註釋：
/*!
* ... 註釋 ...
*/單行型別的註釋：
/// ... 註釋 ...
或
//! ... 註釋 ...備註：不同型別的註釋可以混合使用。
由於Doxygen 對於註釋是視為在解釋後面的程式程式碼。也就是說，任何一個註釋都是在說明其後的程式程式碼。如果要註釋前面的程式程式碼則需用下面格式的註釋符號。
/*!< ... 註釋前面的程式碼 ... */
/**< ... 註釋前面的程式碼... */
//!< ... 註釋前面的程式碼...
///< ... 註釋前面的程式碼...Doxygen產生說明文件時，Doxygen會首先解析程式原始碼，並且依據程式的結構建立對應的文件，然後再將程式碼中的註釋依據其在程式中的位置放在文件中正確的地方。除了一般文字說明外，Doxygen中還有一些其它特別的指令，如@param及@return等。Doxygen根據這些指令判斷註釋的是函式引數還是返回值。例如Doxygen中對檔案的註釋如下所示：
/**
*\file myfile.c
*
*\brief 檔案簡易說明
*
* 詳細說明
*
*\author 作者資訊
*/
\file會告訴Doxygen此處是原始碼檔案的註釋，\brief表明此處是檔案的簡易說明，\author表示的是作者資訊。
對函式說明的註釋如下所示：
/**
* Function 的簡易說明…
* Function的詳細說明…
* @param a 用來相加的引數
* @param b 用來相加的引數
* @return 傳回兩個引數相加的結果
*/
int Function(int a, char b)
{
return (a+b);
}上面這個例子要說的是，在Doxygen處理一個函式註釋時，會先判斷第一行為簡易說明。這個簡易說明將一直到空一行的出現，或是遇到第一個 "." 為止。之後的註釋將會被視為詳細說明。@param表示是函式引數說明。在上面兩個例子中"@"和"\"在Doxygen 中是一樣的，都是告訴Doxygen後面是一個指令。
Doxygen中常用指令的說明如下表所示：
@file | 原始碼檔案的註釋說明。 |
@author | 作者的資訊 |
@brief | 用於class 或function的註釋中，後面為class 或function的簡易說明。 |
@param | 格式為@param arg_name 引數說明 主要用於函式說明中，後面接引數的名字，然後再接關於該引數的說明。 |
@return | 後面接函式傳回值的說明。用於function的註釋中。說明該函式的傳回值。 |
@retval | 格式為@retval value 傳回值說明 主要用於函式說明中，說明特定傳回值的意義。所以後面要先接一個傳回值。然後在放該傳回值的說明。 |
/**
* @file example.c
* @brief 檔案簡要說明
*
* 詳細說明
*
* @author 作者資訊
*/
#define EXAMPLE_OK 0 /**< 註釋EXAMPLE_OK*/
/**
* @brief 結構體簡要說明
*/
typedef struct
{
int member1 ; /**< 註釋member1*/
...
}STRUCT_T;
/**
* Function1() 的簡易說明...
* Function1()的詳細說明...
* @param a 用來相加的引數
* @param b 用來相加的引數
* @return 傳回兩個引數相加的結果
*/
int Function1(int a, char b)
{
return (a+b);
}
/**
* Function2()的簡易說明
*
* @param c 傳進的字元指標
* @retval NULL 空字串
* @retval !NULL 非空字串
*/
char *Function2(char *c)
{
return c;
}四、 Doxygen配置
Doxygen產生文件可以分為三個步驟，一是在程式程式碼中加上符合Doxygen所定義註釋格式；二是使用Doxywizard進行配置；三是使用Doxygen來產生註釋文件。現在我們假定電腦中已經安裝了Doxygen並且程式碼中的註釋已經符合Doxygen規範，下面我們來通過設定配置來生成註釋文件。
1. 圖4.1是Doxygen的主介面，按照介面提示，填寫Doxygen的工作目錄、專案名稱、原始檔目錄、生成文件的存放目錄，同時遞迴搜尋原始檔目錄的選項也要勾選。其中，Doxygen的工作目錄是指用來存放配置檔案的目錄。
圖4.1 Doxygen主介面
2. 選擇Wizard標籤下的Output項，如圖4.2所示
圖4.2Wizard標籤下的Output項的設定
3. 選擇Expert標籤下的Project項，如圖4.3所示。其中，編碼格式，UTF-8是首選。如果需要顯示中文則選擇GB2313。OPTIMIZE_OUTPUT_FOR_C 這個選項選擇後，生成文件的一些描述性名稱會發生變化，主要是符合C習慣。如果是純C程式碼，建議選擇。SUBGROUPING這個選項選擇後，輸出將會按型別分組。
圖4.3Expert標籤下的Project項的設定
4. 選擇Expert標籤下的Build項，如圖4.4所示。這個頁面是生成幫助資訊中比較關鍵的配置頁面：
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 ：是否顯示檔案列表頁面，如果開啟，那麼幫助中會存在一個一個檔案列表索引頁面。
圖4.4 Expert標籤下的Build項的設定
5. 選擇Expert標籤下的Input項，如圖4.5所示。其中輸入的原始檔的編碼，要與原始檔的編碼格式相同。如果原始檔不是UTF-8編碼最好轉一下。
圖4.5Expert標籤下的Input項的設定
6. 選擇Expert標籤下的HTML項，如圖4.6所示。為了解決DoxyGen生成的檔案的左邊樹目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312即可。GENERATE_CHI 表示索引檔案是否單獨輸出，建議關閉。否則每次生成兩個檔案，比較麻煩。TOC_EXPAND 表示是否在索引中列舉成員名稱以及分組（譬如函式，列舉）名稱。
7. 選擇 Run 標籤，如圖4.7所示。點Run doxygen按鈕，Doxygen 就會從原始碼中抓取符合規範的註釋生成定製的格式的文件。
圖4.7 選擇Run標籤下的Rundoxygen按鈕