最近寫(xiě)了一個(gè)小項(xiàng)目，想做完善點(diǎn)，就想到要有一個(gè)API的文檔。知道有很多工具可以自動(dòng)生成，但是具體一直沒(méi)實(shí)現(xiàn)過(guò)，正好利用這個(gè)機(jī)會(huì)實(shí)驗(yàn)一把。
剛開(kāi)始搜索了下，基本鎖定有這兩種工具:
HeaderDoc 是蘋(píng)果官方的文檔生成工具。好處是Xcode自帶了，生成的文檔風(fēng)格和Apple官方的保持一致，支持的語(yǔ)言比較多。缺點(diǎn)是可調(diào)教的地方比較少，注釋的風(fēng)格要求比較嚴(yán)格等；貌似除了Apple外，其他使用的人比較少；最主要的是很多博文里鏈接到官方的地址都不存在了
appledoc 是比較專(zhuān)一的，只為Objective-C服務(wù)，能生成和Apple一個(gè)風(fēng)格的文檔，功能齊全，使用方便，可以直接編輯成docset安裝進(jìn)Xcode。缺點(diǎn)是支持的語(yǔ)言少。
最終我決定使用appledoc生成
安裝 appledoc
git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh
安裝完驗(yàn)證一下版本OK了
appledoc --version
生成API文檔
這里說(shuō)兩種方法：
- 終端命令生成
cd到你項(xiàng)目所在的目錄，然后再運(yùn)行下面命令，然后就編譯出docset并安裝進(jìn)Xcode。注意下面替換成你的工程名稱(chēng)和公司名稱(chēng)
appledoc --project-name 工程名稱(chēng) --project-company 公司名稱(chēng) ./
- Run Script 集成在項(xiàng)目?jī)?nèi)
這個(gè)方法就是把生成方式放在項(xiàng)目?jī)?nèi)啦，方便更新文檔而已。缺點(diǎn)是得為每個(gè)項(xiàng)目添加，看個(gè)人情況使用吧。
1、選中你的項(xiàng)目，點(diǎn)擊 Add Target 按鈕，選擇Cross-platform --> Aggregate
2、點(diǎn)擊Add Build Phase 按鈕，添加一個(gè)Run Script。
3、把下面的模板嗲嗎復(fù)制進(jìn)入，把前幾行參數(shù)改成自己的。
4、在Xcode左上角選擇這個(gè)新建的Target，然后build。
5、文檔就會(huì)編譯好并且自動(dòng)安裝進(jìn)Xcode了（重啟Xcode生效）。
#appledoc Xcode script
# Start constants
company="公司名稱(chēng)";
companyID="com.公司id";
companyURL="http://公司網(wǎng)址";
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 2 \
"${PROJECT_DIR}"
語(yǔ)法
首先，文檔中的注釋只有符合規(guī)范，才能被appledoc認(rèn)可
凡是以"http:///"、"/*"或"/!"開(kāi)頭的注釋塊，都算是appledoc注釋。下面是實(shí)例：
///這是單行注釋
/** 這也是單行注釋/
/*！ 這也是單行注釋/
/** 這也是單行注釋?zhuān)?br> * 第二行會(huì)接上第一行
*/
注釋塊中,每一行的開(kāi)頭的空格和“*”字符多數(shù)情況都會(huì)被appledoc忽略。
連續(xù)的兩行（即沒(méi)有間隔空行）的注釋?zhuān)瑢⒈缓喜⒊梢粋€(gè)段落，并忽略換行，就想html。
在注釋塊中，appledoc支持如下語(yǔ)法：Markdowm、HTML、HeaderDoc Tags。
- Markdown的語(yǔ)法在這里中文翻譯介紹,比較簡(jiǎn)單，學(xué)習(xí)成本不高，簡(jiǎn)書(shū)寫(xiě)博文不就是這個(gè)嘛，大家可以學(xué)習(xí)一下。
- HTML 略。喜歡的直接碼HTML吧
- HeaderDoc Tags 這個(gè)是蘋(píng)果官方的，也是我們常用的了。例如：@param、@return、@warning醬紫的東西。官方文檔我也沒(méi)找到，找到的童鞋麻煩告訴我，多謝。不過(guò)貌似appledoc對(duì)這個(gè)的支持也不完美。
下面是一些大家都可以搜到的語(yǔ)法示意啦：
///這里是屬性的說(shuō)明
@property (nonatomic, strong) NSString *name;
/**
@brief 這里是方法的簡(jiǎn)介。該Tag不能放到類(lèi)注釋里。
@exception UIColorException 這里是方法拋出異常的說(shuō)明
@see YYColor
@see someMethod:
@warning 這里是警告，會(huì)顯示成藍(lán)色的框框
@bug 這里是bug，會(huì)顯示成黃色的框框
@param red 這里是參數(shù)說(shuō)明1
@param green 這里是參數(shù)說(shuō)明2
@param blue 這里是參數(shù)說(shuō)明3
@return 這里是返回值說(shuō)明
*/
-(UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;
-(void)someMethod:(NSString *)str;
@end
最后
編譯完成的Docset默認(rèn)會(huì)放在/Users/用戶(hù)名/Library/Developer/Shared/Documentation/DocSets路徑下
閱讀在Xcode --> Window-->Documentation And API Reference 里面找啦，快捷鍵就是command+shift+0
