使用Objective-C的文檔產生工具:appledoc

標籤：

 

使用Objective-C的文檔產生工具:appledoc

前言

做項目的人多了，就需要文檔了。今天開始嘗試寫一些項目文檔。但是就原始碼來說，文檔最好和源碼在一起，這樣更新起來更加方便和順手。象 Java 語言本身就內建 javadoc 命令，可以從源碼中抽取文檔。今天抽空調研了一下 objective-c 語言的類似工具。

從 stackoverflow 上找到三個比較 popular 的工具：doxygen, headdoc 和 appledoc 。它們分別的官方網址如下：

• docxygen http://www.stack.nl/~dimitri/doxygen/index.html
• headdoc http://developer.apple.com/opensource/tools/headerdoc.html
• appledoc http://gentlebytes.com/appledoc/

介紹

我把這 3 個工具都大概調研了一下，說一下我的感受。

docxygen

docxygen 感覺是這 3 個工具中支援語言最多的，可以配置的地方也比較多。我大概看了一下文檔，覺得還是比較複雜，而且預設產生的風格與蘋果的風格不一致。就去看後面 2 個工具的介紹了。另外，它雖然是開源軟體，但是沒有將源碼放到 github 上讓我感覺這個工具的開發活躍度是不是不夠。

headerdoc

headerdoc 是 Xcode 內建的文檔產生工具。在安裝完 Xcode 後，就可以用命令列：headdoc2html + 源檔案名稱 來產生對應的文檔。我個人試用了一下，還是比較方便的，不過 headerdoc 的注釋建置規則比較特別，只產生以 /\*! \*/ 的格式的注釋。還有一個缺點是每個類檔案對應一個注釋檔案，沒有匯總的檔案，這點感覺有點不爽。

appledoc

appledoc 是在 stackoverflow 上被大家推薦的一個注釋工具。有幾個原因造成我比較喜歡它：

1. 它預設產生的文檔風格和蘋果的官方文檔是一致的，而 doxygen 需要另外配置。
2. appledoc 就是用 objective-c 產生的，必要的時候調試和改動也比較方便。
3. 可以產生 docset，並且整合到 Xcode 中。這一點是很贊的，相當於在源碼中按住 option 再單擊就可以調出相應方法的協助。
4. appledoc 源碼在 github 上，而 doxygen 在 svn 上。我個人比較偏激地認為比較活躍的開源項目都應該在 github 上。
5. 相對於 headerdoc，它沒有特殊的注釋要求，可以用 /\*\* \*/ 的格式，也可以相容 /\*! \*/ 的格式的注釋，並且產生的注釋有匯總頁面。

安裝

那麼簡單介紹一下如何安裝 appledoc，安裝非常簡單，只需要 2 步：

git clone git://github.com/tomaz/appledoc.gitcd appledocsudo sh install-appledoc.sh

 

使用

使用 appledoc 時，只需要用如下命令即可：

appledoc -o ./doc --project-name ynote --project-company youdao .

 

appledoc 會掃描當前路徑下的所有檔案，然後產生好文檔放到 doc 目錄下。你也可以用 appledoc --help 查看所有可用的參數。

基本上使用起來還是比較方便的，詳細的資訊可以查看官方的文檔：http://gentlebytes.com/appledoc/

使用Objective-C的文檔產生工具:appledoc