如 Javadoc 的程式文件產生器 Doxygen 簡易教學
小蛙之前寫 Java 居多，Java 裡面有一個 Javadoc 可以把開發者依照固定好的格式填寫的程式註解整理成一份完整的 HTML 文件，讓其他開發者可以很方便的查詢 API。例如：舊版 Javadoc、新版 Javadoc。這裡有編寫 Javadoc 的一些規則跟說明。前陣子要把寫好的 PHP 整理成類似 Javadoc 這種文件，雖然網路上找到像 phpDocumentor、PHPDoc … 等工具，但覺得不是那麼樣好看(小蛙個人喜好問題，看習慣 Javadoc 了)，這篇文章很簡單地介紹 Doxygen 這套功能強大、設定也挺複雜的文件產生工具。
從 Google 上種種文件看起來，早期的 Doxygen 要自己手動設定一大堆參數(從這篇文章可以看見，其實現在的也是)，小蛙下載完之後發現已經有了 GUI 工具了，以下只簡單介紹小蛙自己有使用到的功能！首先，到 Doxygen 官網的下載頁面下載新版本的 Doxygen (測試當時下載了 doxygen-1.8.3.1-setup.exe (17.2MB) ( ftp | http ) 這個版本)
安裝完成後執行 Doxywizard 開啟 GUI 設定工具。下圖為 Doxywizard 啟動畫面，在 Step 1. 的地方，選擇要製作 document 的路徑，例如：小蛙這邊某個專案的 library 都放在 Include 資料夾下，所以選擇這個資料夾。Step 2. 的部份可以輸入專案名稱、專案簡介、專案版本，甚至是專案LOGO；接著 Specify the directory to scan for source code 跟 Step 1. 是接在一起的，因為 Step 1. 小蛙已經選好目的資料夾了，所以這邊只要輸入 . ，表示該目錄，如果目錄下還有其他階層目錄，把 Scan recursively 打勾；最下面指定產生出來的文件要放在哪個資料夾(Destination directory)。
[pe2-image src=”//lh6.ggpht.com/-GR50oBdr0Mw/UUgcjjXfE-I/AAAAAAAAHic/uifJ6ToyNE4/s144-c/1_doxygen_index.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962712510075874″ caption=”” type=”image” alt=”1_doxygen_index.png” ]
Wizard 下的 Mode 頁面右邊 entities 部份小蛙使用預設值，下面選擇自己的程式語言。
[pe2-image src=”//lh6.ggpht.com/-m23Na2ZnEZo/UUgckCfl-mI/AAAAAAAAHis/t0mLV4VLiBo/s144-c/2_doxygen_mode.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962720865581666″ caption=”” type=”image” alt=”2_doxygen_mode.png” ]
Wizard 下的 Output 頁面 HTML 部份勾選 with navigation panel 就會出現有導覽視窗的文件，另外下方還可以輸出 LaTex、Man Page、RTF、XML … 等等，可依照自己的需求選取。
[pe2-image src=”//lh4.ggpht.com/-rmq-oyQim6c/UUgckGw7I5I/AAAAAAAAHiw/acDDPyYjuZM/s144-c/3_doxygen_output.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962722012013458″ caption=”” type=”image” alt=”3_doxygen_output.png” ]
Wizard 下的 Diagrams 頁面小蛙直接使用預設值，這是會在每個 class 頁面的上方畫出對應的 UML 圖。
[pe2-image src=”//lh6.ggpht.com/-r_7vWpmVLPA/UUgckUcMTOI/AAAAAAAAHio/BYluWo0Uy9s/s144-c/4_doxygen_diagrams.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962725683154146″ caption=”” type=”image” alt=”4_doxygen_diagrams.png” ]
接著切換到 Expert 頁面，這邊的設定有點複雜，小蛙大部分保留預設設定，如果產出的文件有亂碼的情況，才來改這邊的設定，Project 頁面裡的 DOXYFILE_ENCODING、OUTPUT_LANGUAGE；以及 Input 頁面裡的 INPUT_ENCODING。
[pe2-image src=”//lh3.ggpht.com/-ykvStgaNL-g/UUgckv6Y_SI/AAAAAAAAHh8/WgI6_KbyLVo/s144-c/5_doxygen_expert_encoding.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962733057572130″ caption=”” type=”image” alt=”5_doxygen_expert_encoding.png” ]
[pe2-image src=”//lh5.ggpht.com/-8ja6NMgUtqo/UUgckseidII/AAAAAAAAHiY/8ZMTH_tDEVA/s144-c/6_doxygen_expert_encoding.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962732135445634″ caption=”” type=”image” alt=”6_doxygen_expert_encoding.png” ]
還有一個要設定的部份，如果您的專案原始碼是私密的，只有自己人可以看到的話，Source Browser 下的 SOURCE_BROWSER 千萬別打勾；但對於文件放在內網的情況下，在 document 下可以直接看到原始碼也是一件方便的事情！
[pe2-image src=”//lh5.ggpht.com/-snpQOkvJxmU/UUgck-EpQdI/AAAAAAAAHiQ/Iw8u8tkd1Vo/s144-c/7_doxygen_expert_source_browser.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962736858677714″ caption=”” type=”image” alt=”7_doxygen_expert_source_browser.png” ]
最後切換到 Run 頁面，點選 Run doxygen 開始產生文件。
[pe2-image src=”//lh3.ggpht.com/-2GM2PF38JPc/UUgclHYG9yI/AAAAAAAAHiM/-pQRevbgaQ0/s144-c/8_doxygen_run_result.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962739356235554″ caption=”” type=”image” alt=”8_doxygen_run_result.png” ]
以下是結果圖：
[pe2-image src=”//lh3.ggpht.com/-obEzoWzz_WU/UUgclO-6_HI/AAAAAAAAHiU/6OC5ty3tQ5M/s144-c/9_doxygen_data_structures.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962741398076530″ caption=”” type=”image” alt=”9_doxygen_data_structures.png” ]
[pe2-image src=”//lh4.ggpht.com/-84glK3f2aXo/UUgcjujNabI/AAAAAAAAHik/FdPHzDA9AuI/s144-c/10_doxygen_methods.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962715512039858″ caption=”” type=”image” alt=”10_doxygen_methods.png” ]
[pe2-image src=”//lh5.ggpht.com/-3AoqSiJqiXg/UUgcjiii2OI/AAAAAAAAHig/_8G5sBigw44/s144-c/11_doxygen_diagrams.png” href=”https://picasaweb.google.com/116442387221799758778/apWIWG?authkey=Gv1sRgCKTIvqS13OviZQ#5856962712288024802″ caption=”” type=”image” alt=”11_doxygen_diagrams.png” ]
參考資料：
- How to Write Doc Comments for the Javadoc Tool @ Oracle
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html - Java™ Platform Standard Ed. 6 @ Oracle
http://docs.oracle.com/javase/6/docs/api/ - Java™ Platform Standard Ed. 7 @ Oracle
http://docs.oracle.com/javase/7/docs/api/ - phpDocumentor
http://www.phpdoc.org/ - PHPDoc
http://www.phpdoc.de/demo.html - PEAR：使用PHPDoc轻松建立你的PEAR文档 @ IBM
http://www.ibm.com/developerworks/cn/linux/sdk/php/pear3/index.html - 簡介Doxygen by Gary W. Lee
http://www.stack.nl/~dimitri/doxygen/doxygen_intro_cn.html - Doxygen
http://www.stack.nl/~dimitri/doxygen/download.html - Doxygen 程式文件產生器 與 簡易筆記 @ Tsung’s Blog
http://blog.longwin.com.tw/2011/04/doxygen-document-generator-2011/