參考資料1
參考資料2
從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/
介紹
docxygen
docxygen感覺是這3個工具中支援語言最多的，可以配置的地方也比較多。我大概看了一下文檔，覺得還是比較複雜，而且預設生成的風格與蘋果的風格不一緻。就去看後面2個工具的介紹了。另外，它雖然是開源軟體，但是沒有将源碼放到github上讓我感覺這個工具的開發活躍度是不是不夠。
headerdoc
headerdoc是xcode 自帶的文檔生成工具。在安裝完xcode後，就可以用指令行：headdoc2html + 源檔案名 來生成對應的文檔。我個人試用了一下，還是比較友善的，不過headerdoc的注釋生成規則比較特别，隻生成以
的格式的注釋。還有一個缺點是每個類檔案對應一個注釋檔案，沒有彙總的檔案，這點感覺有點不爽。
appledoc
appledoc是在stackoverflow上被大家推薦的一個注釋工具。有幾個原因造成我比較喜歡它：
它預設生成的文檔風格和蘋果的官方文檔是一緻的，而doxygen需要另外配置。
appledoc就是用objective-c生成的，必要的時候調試和改動也比較友善。
可以生成docset，并且內建到xcode中。這一點是很贊的，相當于在源碼中按住option再單擊就可以調出相應方法的幫助。
appledoc源碼在github上，而doxygen在svn上。我個人比較偏激地認為比較活躍的開源項目都應該在github上。
相對于headerdoc，它沒有特殊的注釋要求，可以用
的格式，也可以相容
的格式的注釋，并且生成的注釋有彙總頁面。
安裝
那麼簡單介紹一下如何安裝appledoc，安裝非常簡單，隻需要2步：
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
其他方法：
brew install appledoc
自己編譯：去Github把工程clone下來，用Xcode打開，然後随便搞。。
安裝完成後，驗證一下OK了沒:
appledoc –version
使用
使用appledoc時，隻需要用如下指令即可：
appledoc會掃描目前路徑下的所有檔案，然後生成好文檔放到doc目錄下。
如果想要詳細的參數，可以檢視幫助
如果想要內建進Xcode工程:
1.選中你的工程,點選Add Target按鈕,選擇 Other -> Aggregate模闆建立.
2.點選Add Build Phase按鈕,添加一個Run Script.
3.把下面的模闆代碼複制進去,把前幾行參數改成你自己的.
4.在Xcode左上角選擇這個建立的Target,然後點選build.
5.文檔就會編譯好并且自動安裝進Xcode了(重新開機Xcode生效).
#appledoc Xcode script
# Start constants
company="ACME";
companyID="com.ACME";
companyURL="http://ACME.com";
target="iphoneos";
#target="macosx";
outputPath="~/help";
# End constants
/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/${company}" \
--output "${outputPath}" \
--publish-docset \
--docset-platform-family "${target}" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold \
"${PROJECT_DIR}"
文法
appledoc官方原來是有一篇文法的，但是現在貌似維護中了。。是以這裡盡量多介紹一下。
首先，文檔中的注釋隻有符合規範，才能被appledoc認可。
凡是以
"///"
、
"/**"
或
"/*!"
開頭的注釋塊，都算所appledoc注釋。下面是示例:
/// 這是單行注釋。
/** 這也是單行注釋 */
/*! 同樣是單行注釋 */
/** 這也是單行注釋，
* 第二行會接上第一行。
*/
注釋塊中，每一行開頭的空格和”*”字元多數情況都會被appledoc忽略。
連續的兩行(即沒有間隔空行)的注釋，将被合并成一個段落，并忽略換行，就像html。
在注釋塊内，appledoc支援如下文法：Markdown、HTML、HeaderDoc Tags。
Markdown的文法在這裡有介紹(中文翻譯)，用Github的童鞋應該很熟悉。OSX上可以用Mou實時檢視效果，Chrome也有一個插件來實時檢視效果。這個東西可以說一看就會，學習成本很低。Markdown有很多方言，而且appledoc支援的也不算完整。是以用的時候可以試着在appledoc編譯一下看看效果。
HTML這個就不用說了，支援Markdown肯定也支援HTML。。如果想要把控住更多細節，那就直接碼Html吧。
HeaderDoc Tags這個東西是蘋果的HeaderDoc工具的文法。詳情可以見官網文檔。例如@param、@return、@warning這樣的東西，appledoc會進行解釋。當然appledoc對這個東西的支援也不算完整 :?: 是以用的時候也要嘗試一下。
通常情況下，Xcode會給關鍵詞高亮顯示，就像下面這樣：
下面是一些常用的文法示意:
/** 第一行是類的簡介
在簡介的下面,就是類的詳細介紹了。
沒有間隔換行會被消除，就像Html那樣。
下面是常用的markdown文法
- - -
無序清單: (每行以 '*'、'-'、'+' 開頭):
* this is the first line
* this is the second line
* this is the third line
有序清單: (每行以 1.2.3、a.b.c 開頭):
a. this is the first line
b. this is the secode line
多級清單:
* this is the first line
a. this is line a
b. this is line b
* this is the second line
1. this in line 1
2. this is line 2
标題:
# This is an H1
## This is an H2
### This is an H3
#### This is an h4
##### This is an h5
###### This is an H6
連結:
普通URL直接寫上，appledoc會自動翻譯成連結: http://blog.ibireme.com
[這個](http://example.net/) 連結會隐藏實際URL.
表格:
| header1 | header2 | header3 |
|---------|:-------:|--------:|
| normal | center | right |
| cell | cell | cell |
引用:
這裡會引用到方法 `someMethod:`，這裡會引用到類 `YYColor`
這裡會引用到一個代碼塊
void CMYK2RGB(float c, float m, float y, float k,
float *r, float *g, float *b) {
*r = (1 - c) * (1 - k);
*g = (1 - m) * (1 - k);
*b = (1 - y) * (1 - k);
}
@since iOS5.0
*/
@interface AppledocExample : NSObject
///這裡是屬性的說明
@property (nonatomic, strong) NSString *name;
/**
@brief 這裡是方法的簡介。該Tag不能放到類注釋裡。
@exception UIColorException 這裡是方法抛出異常的說明
@see YYColor
@see someMethod:
@warning 這裡是警告，會顯示成藍色的框框
@bug 這裡是bug，會顯示成黃色的框框
@param red 這裡是參數說明1
@param green 這裡是參數說明2
@param blue 這裡是參數說明3
@return 這裡是傳回值說明
*/
- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;
- (void)someMethod:(NSString *)str;
@end
編譯出的效果是這樣：
appledoc還有很多不太完善的地方，比如C方法和宏定義上面的注釋就不被識别，URL連結有時會識别錯誤等。。這時候隻能手動修改生成好的html了；或者比較勤快自己手動fork一個appledoc改一下。。
其他
編譯出的Docset預設會放在
/Users/ibireme/Library/Developer/Shared/Documentation/DocSets
路徑下。
Docset格式，實際上是一個bundle,裡面包含了一些xml和html。顯示包内容後就可以檢視和修改了。如果需要放到網站上，那單獨将html部分取出來就行。
Docset安裝後，在Xcode中就可以實時檢視某個方法的說明了，體驗和官方文檔保持一緻。（有一點，category中的注釋不會出現在xcode的快速幫助中，不知道新版xcode是否會有改進..）