文檔生成器——Doxygen
一、簡介
Doxygen是一種開源跨平台的，以類似JavaDoc（java開發環境自帶的API文檔生成工具）風格描述的文檔系統，完全支持C、C++、Java、Objective-C和IDL語言，部分支持PHP、C#。注釋的語法與Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以從一套歸檔源文件（根據文件的形成規律和特點,保持文件之間的有機聯系,區分不同價值,便於保管和利用的文件整理。）開始，生成HTML格式的在線類瀏覽器，或離線的LATEX、RTF參考手冊。
二、功能及特點
Doxygen 是一個程序的文件產生工具，可將程序中的特定批注轉換成為說明文件。減輕程序維護負擔，添加文件整理負擔。
三、安裝相關程序
本文使用的為Doxygen 1.8.14
3.1、Doxygen
下載地址：http://sourceforge.net/projects/doxygen/?source=dlp
我們將在配置的時候使用doxywizard，Doxygen的GUI版本。
3.2、HTML Help Workshop
如果你希望你的Doxygen自動生成chm，那么請下載HTML Help Workshop，我們將要使用當中的hcc.exe文件以及相關dll下載地址：http://www.microsoft.com/en-us/download/details.aspx?id=21138
下載其中的htmlhelp.exe並安裝，記住安裝目錄，我們將在Doxygen配置時使用。
3.3、 Graphviz
graphviz 是一個由AT&T實驗室啟動的開源工具包，用於繪制DOT語言腳本描述的圖形。Doxygen 使用 graphviz 自動生成類之間和文件之間的調用關系圖，如不需要此功能可不安裝該工具包。
下載地址：https://graphviz.gitlab.io/download/
安裝並記錄安裝目錄，同樣我們一會在配置Doxygen時使用。
添加系統環境變量：.建立變量名GRAPHVIZ_DOT值為安裝的路徑C:\Program Files (x86)\Graphviz2.34\bin\dot.exe，在用戶環境變量添加以下一個變量，建立變量名 GRAPHVIZ_INSTALL_DIR, 值為如C:\Program Files (x86)\Graphviz2.34， 在系統環境變量中建立變量名PATH中添加Graphviz的bin目錄路徑，如C:\Program Files (x86)\Graphviz2.34\bin
四、使用（請勿包含中文路徑）
Doxygen 產生文檔可以分為三個步驟。一是在程序代碼中加上符合Doxygen所定義批注格式。二是使用Doxywizard進行配置。三是使用Doxygen來產生批注文檔。
4.1、wizard 標簽下的 Project
Doxygen 目錄，就是用來存放配置文件的目錄（每生成一次文檔退出時可選擇保存本次配置）。
4.2、wizard 標簽下的 Output
4.3、wizard 標簽下的 Diagrams
選擇這個選項之前需要先安裝 Graphviz 工具包
4.4、expert 標簽下的 Project
編碼格式，UTF-8 是首選。如果需要顯示中文則選擇GB2312.（vs c#采用utf-8）
TAB_SIZE 主要是幫助文件中代碼的縮進尺寸，譬如@code和@endcode段中代碼的排版，建議設置成4。
OPTIMIZE_OUTPUT_FOR_C 這個選項選擇后，生成文檔的一些描述性名稱會發生變化，主要是符合C習慣。如果是純C代碼，建議選擇。
SUBGROUPING這個選項選擇后，輸出將會按類型分組。
4.5、expert 標簽下的 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 ：是否顯示文件列表頁面，如果開啟，那么幫助中會存在一個一個文件列表索引頁面。
4.6、expert 標簽下的 Input
4.7、expert 標簽下的 HTML
若chm文件名為中文，生成的文檔名會亂碼。文件名在文檔生成后可重命名。
CHM_FILE文件名需要加上后綴（xx.chm）。
如果在 Wizard 的 Output Topics 中選擇了 prepare for compressed HTML (.chm)選項，此處就會要求選擇 hhc.exe 程序的位置。在 windows help workshop 安裝目錄下可以找到 hhc.exe。
為了解決DoxyGen生成的CHM文件的左邊樹目錄的中文變成了亂碼，CHM_INDEX_ENCODING中輸入GB2312即可。
GENERATE_CHI 表示索引文件是否單獨輸出，建議關閉。否則每次生成兩個文件，比較麻煩。
TOC_EXPAND 表示是否在索引中列舉成員名稱以及分組（譬如函數，枚舉）名稱。
4.8、選擇 Run 標簽
五、問題及解決方案
5.1、文檔生成成功但無內置圖片
原因： graphviz 安裝配置錯誤
5.2、轉碼失敗
原因及方案：確認並修改源文件編碼格式