小蛙之前寫 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)。

1_doxygen_index.png

Wizard 下的 Mode 頁面右邊 entities 部份小蛙使用預設值,下面選擇自己的程式語言。

2_doxygen_mode.png

 Wizard 下的 Output 頁面 HTML 部份勾選 with navigation panel 就會出現有導覽視窗的文件,另外下方還可以輸出 LaTex、Man Page、RTF、XML … 等等,可依照自己的需求選取。

3_doxygen_output.png

 Wizard 下的 Diagrams 頁面小蛙直接使用預設值,這是會在每個 class 頁面的上方畫出對應的 UML 圖。

4_doxygen_diagrams.png

接著切換到 Expert 頁面,這邊的設定有點複雜,小蛙大部分保留預設設定,如果產出的文件有亂碼的情況,才來改這邊的設定,Project 頁面裡的 DOXYFILE_ENCODINGOUTPUT_LANGUAGE;以及 Input 頁面裡的 INPUT_ENCODING

5_doxygen_expert_encoding.png

6_doxygen_expert_encoding.png

還有一個要設定的部份,如果您的專案原始碼是私密的,只有自己人可以看到的話,Source Browser 下的 SOURCE_BROWSER 千萬別打勾;但對於文件放在內網的情況下,在 document 下可以直接看到原始碼也是一件方便的事情!

7_doxygen_expert_source_browser.png

最後切換到 Run 頁面,點選 Run doxygen 開始產生文件。

8_doxygen_run_result.png

以下是結果圖:

9_doxygen_data_structures.png

10_doxygen_methods.png

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/
相關文章

SSL For Free – 免費又有綠色鎖頭的 SSL Certificates

之前聽說 Google 會優先搜尋有 https 的網頁 (參考:
2016-07-07 23:00:54
hans

8

Android Vuforia with jPCT-AE (5) – 多重模型載入,以 obj 為例

要進到這系列最後一篇文章了,這篇文章拖了很久,一直沒有時間整理,結果到最後 ... 程式碼留下來了,記憶卻有些模糊了,這邊小蛙配著程式碼盡可能的把還記得的東西寫下來。
2016-07-06 11:24:19
hans

8

Android Vuforia with jPCT-AE (4) – 載入 3DS 測試

延續 jPCT-AE Loader 載入模型的部份,這篇要記錄載入 3ds 檔案格式的方法,基本上跟前面幾個 obj, md2 的方法差不多,只有一些小小的變化而已。
2016-07-06 10:24:33
hans

8

Android Vuforia with jPCT-AE (3) – 載入 md2 測試

前兩篇介紹如何直接透過 jPCT-AE 直接繪圖以及載入 .obj 檔案,這邊繼續介紹 jPCT-AE 載入 md2 的方法,載入動作大致上類似,唯一不同的只有 texture 設定部份。
2016-07-06 09:24:43
hans

8

Android Vuforia with jPCT-AE (2) – 載入 obj 測試

上一篇 Android Vuforia with jPCT-AE (1) –
2016-07-06 08:24:55
hans

8

Android Vuforia with jPCT-AE (1) – 基本範例

說來慚愧,從 Google Adsense 被 ban 之後,就好久沒有發文了,站上 Vuforia 的文章也已經是好久以前的事情了 (遠目),最近有專案要用到 Vuforia,爬以前的文回來看,蛙哩咧 ... 現在已經更新到 Vu
2016-07-06 07:57:58
hans

8

ClickForce (MobiForce) 當機問題

這真是個浪費時間又漫長的過程,CF 推出新版後台以及新版 SDK 的時候,小蛙就下載來測試,一開始小蛙直接套在「我的股票精算師」上,但只要一套上去就當機 ...
2015-09-02 10:32:51
hans

8

我的股票精算師備份功能

常遇到使用者詢問「我的股票精算師」要怎麼備份,這篇記錄一下,需要寫怎麼備份表示軟體設計上有很大的問題,造成使用者使用上的困難,但小蛙最近沒有時間去做修改 ... 只好委屈精算師的使用者了 ><
2015-02-06 18:32:07
hans

8

第一次從淘寶買小米盒子3

最近阿咕有在大螢幕上看韓劇的需求,剛好搭上 Chromecast 的上市,survey 了一些 Android 電視棒。這篇記錄這幾天的經過。

2015-01-04 23:36:33
hans

8




 回覆

你可以使用以下語法 HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <pre class="">

(required)

(required)

   
© 2012 蛙齋 Suffusion theme by Sayontan Sinha