你有為軟件編寫(xiě)說(shuō)明文檔的苦惱嗎？當(dāng)別人甩給你一個(gè)龐大的系統(tǒng)，讓你根據(jù)里面的代碼注釋理解后寫(xiě)出一份完整的開(kāi)發(fā)文檔，你會(huì)怎么辦？一個(gè)個(gè)的看代碼 然后耗時(shí)N天來(lái)寫(xiě)嗎？這既是一份苦差事也極其耗時(shí)，有沒(méi)有更好的辦法呢？比如根據(jù)代碼注釋自動(dòng)生成詳盡的說(shuō)明文檔……可能有人會(huì)說(shuō)用Javadoc就是 了，要是C/C++、Python、C#等語(yǔ)言寫(xiě)的軟件呢？有沒(méi)有類(lèi)似Javadoc的東西？
Yes，當(dāng)然有，Doxygen就是這樣一個(gè)能滿足你需求的工具。Doxygen是一種開(kāi)源跨平臺(tái)的，以類(lèi)似JavaDoc風(fēng)格描述的文檔系統(tǒng)，完全支持C、C++、Java、Objective-C和IDL語(yǔ)言，部分支持PHP、C#。注釋的語(yǔ)法與Qt-Doc、KDoc和JavaDoc兼容。Doxgen可以從一套歸檔源文件開(kāi)始，可將程序中的特定批注轉(zhuǎn)換成為說(shuō)明文件，生成HTML格式的在線類(lèi)瀏覽器，或離線的LATEX、RTF參考手冊(cè)。被Boost、OpenCasCade等諸多項(xiàng)目作為文檔生成工具的不二選擇。
由于我主要的開(kāi)發(fā)語(yǔ)言是Java，所以在這里主要說(shuō)明Doxygen在Eclipse里的集成及使用步驟。
1. 安裝doxygen工具
在集成之前需要安裝doxygen工具，下載方法有兩種：目前最新版是1.8.6
（1）官方網(wǎng)站下載（建議）：Doxygen：Downloads
（2）在sourceforge下載：Doxygen
2.安裝doxygen在Eclipse中的插件：Eclox
建議在其官方網(wǎng)站下載：Eclox
eclox_0.8.0.zip后解壓，安裝插件的方法也有幾種：
1. 將eclox_0.8.0中的plugins和features目錄里的內(nèi)容，移動(dòng)到eclipse中的plugins和features目錄里重啟即可，最簡(jiǎn)單。
2. 通過(guò)links方法安裝插件（建議該方法，具體可Google）。
2. 采用Eclipse里的update manager安裝插件，具體方法請(qǐng)看這里。
注意：網(wǎng)上都說(shuō)同時(shí)要下載eclox.update_0.8.0.zip并解壓安裝，其實(shí)完全沒(méi)必要，eclox.update_0.8.0只是版本的更新過(guò)程，里面包含的都是最新版本和歷史版本插件，而我們需要的只是最新版本的，故不需要下載此壓縮文件。
如果這兩個(gè)步驟都完成后，重啟eclipse之后，就可以發(fā)現(xiàn)在工具欄上多了一個(gè)@的圖標(biāo)，如下圖所示，表示安裝成功。
3. 在Eclipse中配置doxygen運(yùn)行環(huán)境
工具欄上windows->preferences->Doxygen, 點(diǎn)擊Add，添加doxygen安裝目錄中的bin目錄，如下圖所示：
4. 使用Doxygen生成文檔過(guò)程舉例
4.1 自動(dòng)生成工程的doxygen文件
首先選擇你要生成文檔的工程，
然后File->New->others....,出現(xiàn)下面的選擇框，選擇Other中的Doxyfile。
next，配置Doxygen，定好文件的名字，點(diǎn)擊Finish就OK了。
當(dāng)然到此還沒(méi)結(jié)束，最重要的一步還沒(méi)完成，就是自動(dòng)生成doxygen文件后需要我們自己配置各個(gè)參數(shù)和選項(xiàng)。
4.2 配置doxygen文件參數(shù)和選項(xiàng)
配置Doxygen文件參數(shù)也有三種方式：
4.2.1 使用Eclipse中集成的doxygen editor進(jìn)行修改
在Eclipse中打開(kāi)剛剛自動(dòng)生成的doxygen文件，默認(rèn)的配置如下：
比如在Eclipse中我用的配置選項(xiàng)如下：
建議大家如果不理解各個(gè)選項(xiàng)，可以嘗試每個(gè)選項(xiàng)的生成效果，以找出自己最想要的文檔格式。
4.2.2 使用Doxygen安裝程序自帶的GUI工具
找到Doxygen的安裝目錄下的bin目錄里，如下圖所示可以看到有個(gè)GUI工具：
打開(kāi)后如下圖所示：
與Eclipse中大同小異，各個(gè)參數(shù)選項(xiàng)慢慢琢磨吧，很簡(jiǎn)單。
4.2.3 直接用文本編輯器進(jìn)行修改
針對(duì)doxyfile可直接用文本編輯器進(jìn)行編輯，建議用Notepad++或?qū)懽职宓却蜷_(kāi)，不要用無(wú)排版的記事本。
主要有以下內(nèi)容需關(guān)注：
<OUTPUT_DIRECTORY>：必須在這里提供一個(gè)目錄名，例如 /home/user1/documentation，這個(gè)目錄是放置生成的文檔文件的位置。如果提供一個(gè)不存在的目錄名，doxygen 會(huì)以這個(gè)名稱創(chuàng)建具有適當(dāng)用戶權(quán)限的目錄。
<INPUT>：這個(gè)標(biāo)記創(chuàng)建一個(gè)以空格分隔的所有目錄的列表，這個(gè)列表包含需要生成文檔的 C/C++ 源代碼文件和頭文件。如果項(xiàng)目只有一個(gè)源代碼根目錄，其中有多個(gè)子目錄，那么只需指定根目錄并把<RECURSIVE> 標(biāo)記設(shè)置為Yes。
<FILE_PATTERNS>：在默認(rèn)情況下，doxygen 會(huì)搜索具有典型 C/C++ 擴(kuò)展名的文件，比如.c、.cc、.cpp、.h 和.hpp。如果<FILE_PATTERNS> 標(biāo)記沒(méi)有相關(guān)聯(lián)的值，doxygen 就會(huì)這樣做。如果源代碼文件采用不同的命名約定，就應(yīng)該相應(yīng)地更新這個(gè)標(biāo)記。例如，如果項(xiàng)目使用.c86 作為C 文件擴(kuò)展名，就應(yīng)該在<FILE_PATTERNS> 標(biāo)記中添加這個(gè)擴(kuò)展名。
<RECURSIVE>：如果源代碼層次結(jié)構(gòu)是嵌套的，而且需要為所有層次上的 C/C++ 文件生成文檔，就把這個(gè)標(biāo)記設(shè)置為Yes。例如，請(qǐng)考慮源代碼根目錄層次結(jié)構(gòu) /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目錄。如果這個(gè)標(biāo)記設(shè)置為Yes，doxygen 就會(huì)遞歸地搜索整個(gè)層次結(jié)構(gòu)并提取信息。
<EXTRACT_ALL>：這個(gè)標(biāo)記告訴 doxygen，即使各個(gè)類(lèi)或函數(shù)沒(méi)有文檔，也要提取信息。必須把這個(gè)標(biāo)記設(shè)置為Yes。
<EXTRACT_PRIVATE>：把這個(gè)標(biāo)記設(shè)置為Yes。否則，文檔不包含類(lèi)的私有數(shù)據(jù)成員。
<EXTRACT_STATIC>：把這個(gè)標(biāo)記設(shè)置為Yes。否則，文檔不包含文件的靜態(tài)成員（函數(shù)和變量）。
<OUTPUT_LANGUAGE>：默認(rèn) = English，文檔語(yǔ)言（自動(dòng)生成的文字部分），可以指定為Chinese。
<DOXYFILE_ENCODING>：默認(rèn) = UTF-8，默認(rèn)編碼為UTF-8，這樣可以支持中文。
<PROJECT_NAME>：項(xiàng)目名稱，多個(gè)單詞需要使用引號(hào)(“”)。
<PROJECT_NUMBER>：項(xiàng)目版本號(hào)。
4.3 運(yùn)行doxygen文件生成最后的文檔
配置完成后在Eclipse中點(diǎn)擊@插件按鈕選擇doxygen配置文件即可生成文檔了。
可以在控制臺(tái)看到生成詳細(xì)過(guò)程，如果有如何配置錯(cuò)誤如指定的路徑或文件不存在等，都會(huì)給出提示，按要求重新配置即可。
打開(kāi)生成文檔里的index.html（如果是html格式），在瀏覽器查看，點(diǎn)擊各個(gè)選項(xiàng)查看效果如下：
主界面：
喜歡 
頂
難過(guò)
囧
圍觀
無(wú)聊
