Objective-C自動生成文檔工具:appledoc

由于最近瑣事比較多，所以好久沒有寫文章了。今天我們聊一聊Objective-C自動生成文檔。

做項目的人多了，就需要文檔了。手工寫文檔是一件苦差事，但是我們也有從源碼中抽取注釋生成文檔的專用工具。

經過查找，比較大眾的有三個：

doxygen ：適于生成html文檔與pdf文檔。 支持的語言多，可以配置的地方也比較多。默認生成的風格與蘋果的風格不一致。

headdoc ：是 Xcode 自帶的文檔生成工具。在安裝完 Xcode 后，就可以用命令行來生成對應的文檔。不過它只生成以 /*! */ 的格式的注釋。不兼容 /** */ 格式的注釋

appledoc : Github地址 ，適于生成html文檔和xcode幫助文檔（docset）。可以兼容 /** */ 格式，也可以兼容 /*! */ 格式的注釋。

我感覺appledoc是最好的，所以在這里，我只介紹一下appledoc的使用，有興趣的童鞋也可以研究下其他兩種。

appledoc的安裝

第一種：打開終端，輸入以下命令：

git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

第二種：如果你裝了homebrew，打開終端，輸入以下命令：

brew install appledoc

appledoc的使用

為了演示appledoc的使用，我在桌面新建了一個工程Test，然后在ViewController類里面加了一些注釋：

ViewController.h

ViewController.m

然后演示appledoc的使用：

1.在終端中使用

使用 appledoc 時，打開終端，進入項目所在目錄，使用如下命令即可：

appledoc --output 輸出路徑 --project-name 工程名 --project-company 公司名 --company-id 公司ID .

例如我在這里使用的命令是：

appledoc --output ./doc --project-name Test --project-company lisong --company-id lisong .

具體過程如下：

生成Docset

appledoc 會掃描當前路徑下的所有文件，然后生成好文檔放到 doc 目錄下。

doc目錄

編譯出的Docset

默認會放在 ~/Library/Developer/Shared/Documentation/DocSets 路徑下，里面包含html的文檔。首先顯示生成的Docset的包內容，然后在Contents/Resources/Documents路徑下，雙擊打開里面的index.html可以在瀏覽器中查看文檔了。

并且生成的Docset已經安裝到Xcode中。重啟Xcode后，在 Help—Documentation and API Reference 菜單下也可以看到生成的文檔：

在Xcode中查看

如果不想生成Docset，而是想生成html，就需要加一個 --no-create-docset ，這里我使用命令：

appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .

則會在doc目錄下生成一個html文件夾，也是雙擊里面的index.html就可以在瀏覽器中查看文檔了。

html文檔

你也可以在終端用 appledoc --help 查看所有可用的參數。

2.在Xcode里使用

1.首先創建一個Aggregate類型的Target，取名Document

創建Target

2.選擇Build Phases，點擊左邊的小加號，選擇New Run Script Phase，建好了以后打開剛剛建立的Run Script，在框里輸入命令，命令與終端一樣，這里我們輸入：

appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .

添加script

3..然后點左上角選擇Document，編譯一下，成功后文檔就生成在doc目錄下了。

編譯生成文檔

注釋樣式

因為appledoc是通過注釋生成文檔的，下面說說注釋的樣式，幾種常見的有：

/// Single line comment.

/// Single line comment spreading
/// over multiple lines.

/** Single line comment. */

/*! Single line comment */

/** 
 * Single line comment spreading
 * over multiple lines.
 */

/** 
 Single line comment spreading
 over multiple lines. No star
 */

在Xcode里面，我們可以用 command + option + / 方便快捷地生成注釋，很方便。大家可以多嘗試嘗試各種注釋。 

歡迎關注我 和我的專題：iOS技術交流，查看更多好文章。

 

來自：http://www.jianshu.com/p/fd4d8d6b6177