小蛙之前寫 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_ENCODINGOUTPUT_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” ]

參考資料:

  1. How to Write Doc Comments for the Javadoc Tool @ Oracle
    http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
  2. Java™ Platform Standard Ed. 6 @ Oracle
    http://docs.oracle.com/javase/6/docs/api/
  3. Java™ Platform Standard Ed. 7 @ Oracle
    http://docs.oracle.com/javase/7/docs/api/
  4. phpDocumentor
    http://www.phpdoc.org/
  5. PHPDoc
    http://www.phpdoc.de/demo.html
  6. PEAR:使用PHPDoc轻松建立你的PEAR文档 @ IBM
    http://www.ibm.com/developerworks/cn/linux/sdk/php/pear3/index.html
  7. 簡介Doxygen by Gary W. Lee
    http://www.stack.nl/~dimitri/doxygen/doxygen_intro_cn.html
  8. Doxygen
    http://www.stack.nl/~dimitri/doxygen/download.html
  9. Doxygen 程式文件產生器 與 簡易筆記 @ Tsung’s Blog
    http://blog.longwin.com.tw/2011/04/doxygen-document-generator-2011/

發表迴響

你的電子郵件位址並不會被公開。 必要欄位標記為 *