小章魚工作室

一直以來我總是想讓老闆接受程式文件只需要 Javadoc 產生即可, 但老闆總是希望能拿到紙本文件, 於是昨天老闆叫我試試 PDFDoclet.

雖然只是單純的把 Javadoc 輸出成 PDF, 不像 Doxygen 還可以支援 UML 轉換, 但在 Doxygen 還不支援 Java 5.0 的情況下, PDFDoclet 不失為一個好選擇.

設定方式並不複雜, 由它提供的 Ant 範例做些簡單的變動即可, 雖然可以順利產出 PDF 文件, 但所有 Javadoc 全數產出並不是我想達到的效果, 必竟有些細節的部分不太需要, 這時 PDFDoclet 也提供了一個不錯的功能 : filter.

要使用 filter 功能必須在 PDFDoclet 的 Config 檔(.properties) 中設定 filter=true, 並指定要過濾的Tag.

做了這個設定後, 只有 Javadoc 中有包含 @testTagA 或 @testTagB 的內容才會被產生到 PDF 文件中.

而這個功能要注意的一點是: Class 自己的 Javadoc 中必定要有 filter tag, 否則的話, 該 Class 就會被濾掉了, 其中的 Method 有設定也無效囉.(為了這個我搞了一整天.. 囧)

而另一個有趣的功能則是可以由外部文件來加入 Overview 頁面及附錄頁, 目前支援 html 和 PDF file 二種來源, PDF 文件的話還可以指定頁碼範圍, 相當實用, 必竟這類文件多少會需要一些圖表, 或印上公司的 Mark、版權之類的.

今天我就隨手做了有一張相片的 PDF 檔來加入, 效果還不賴啦~


不過這二天測試時也有遇到一些問題, 例如:
1.使用 html 加入時, 中文會變成亂碼.
2.使用預設值完整輸出時, 輸出雖成功但檔案卻是壞的?
(雖說產生出來的檔案近6M..)

第一點改用 PDF 加入就OK, 第二點因為程式還沒全面加上過濾的Tag, 所以暫時不知道後續發展如何... 但就目前為止還滿不錯的, 有需要的人可以參考看看.