總體效果及語法
AppleDoc可以根據(jù)項(xiàng)目中的注釋自動(dòng)生成類似于Apple官方文檔的文檔文件，大致的效果類似于這樣：
文檔總目錄
展開樣式
效果看上去還算不錯(cuò)，但是AppleDoc還是有一些限制的，就是要在代碼中加上注釋，而且只支持/**/、///、//等格式，不支持#pragma mark - WKNavigationDelegate。
- appledoc 支持的注釋類型
/// 這是單行注釋。
/** 這也是單行注釋 */
/*! 同樣是單行注釋 */
/** 這也是單行注釋，
* 第二行會(huì)接上第一行。
*/
/** 第一行是類的簡介
在簡介的下面,就是類的詳細(xì)介紹了。
沒有間隔換行會(huì)被消除，就像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
多級(jí)列表:
* 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
標(biāo)題:
# 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會(huì)自動(dòng)翻譯成鏈接: http:// blog.ibireme.com
[這個(gè)](http://example.net/) 鏈接會(huì)隱藏實(shí)際URL.
表格:
| header1 | header2 | header3 |
|---------|:-------:|--------:|
| normal | center | right |
| cell | cell | cell |
引用:
這里會(huì)引用到方法 `someMethod:`，這里會(huì)引用到類 `YYColor`
這里會(huì)引用到一個(gè)代碼塊
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 這里是警告，會(huì)顯示成藍(lán)色的框框
@bug 這里是bug，會(huì)顯示成黃色的框框
@param red 這里是參數(shù)說明1
@param green 這里是參數(shù)說明2
@param blue 這里是參數(shù)說明3
@return 這里是返回值說明
*/
- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;
- (void)someMethod:(NSString *)str;
@end
- Github鏈接：https://github.com/tomaz/appledoc
安裝
git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh
完成后可以用appledoc --version驗(yàn)證下。
驗(yàn)證
使用
-
首先cd到你的項(xiàng)目文件夾下。
跑一下下面的命令，默認(rèn)會(huì)編譯出docset并安裝進(jìn)Xcode。appledoc --project-name 你的項(xiàng)目名稱 --project-company 你的公司名稱 ./
然后你的項(xiàng)目文件夾中就會(huì)出現(xiàn)這樣一個(gè)文件
文件
- 其次將appledoc集成到我們自己的工程中
集成
集成
- 下一步將下方腳本黏貼到runScript
集成
#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 2 \
"${PROJECT_DIR}"
- 最后選擇這個(gè)target編譯下就好了
編譯
ps:如果這一步有出錯(cuò)，就退出xcode再編譯一次就好了。
生成的目錄包就在剛才的docset-installed.txt中
結(jié)果
結(jié)果
結(jié)果
好了，以上就是全部過程，還是挺方便的。
總結(jié)
能夠根據(jù)注釋自動(dòng)生成類似于apple官方文檔的功能固然很強(qiáng)大，但是對(duì)開發(fā)人員來說，還是直接看自己的注釋來的實(shí)在方便。
不過，如果需要給CTO或者老板一份代碼報(bào)告的話，用這個(gè)工具還是很方便（裝X）的。O(∩_∩)O
我是翻滾的牛寶寶，歡迎大家評(píng)論交流~
