安裝
- mac終端使用以下命令下載工具源碼
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
- 安裝成功提示如下
** INSTALL SUCCEEDED **
生成API文檔
首先建一個(gè)Demo工程名稱叫TestAppleDoc
- 終端命令生成
cd xxx/TestAppleDoc
appledoc --project-name 工程名稱 --project-company lengyi(公司名稱) ./
- 項(xiàng)目工程添加腳本自動(dòng)生成 （方便更新文檔）
1、選中項(xiàng)目，點(diǎn)擊Add Target按鈕，選擇Cross-platform --> Aggregate
2、點(diǎn)擊Add Build Phase 按鈕，添加一個(gè)Run Script
3、添加下面的腳本代碼,把前面幾行改成自己的
4、在Xcode左上角選中新建的Target,然后build
5、文檔就會(huì)編譯好并自動(dòng)安裝進(jìn)Xcode （每次編譯問需要重啟Xcode才能看到最新的文檔）
#appledoc Xcode script
# Start constants
company="lengyi";
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}"
步驟.png
語法
文檔中的注釋只有符合規(guī)范，才能被appledoc認(rèn)可，凡是以 "http:///"、 "/*"、 "/!"開頭的注釋都算是appledoc注釋
/// 這是單行注釋。
/** 這也是單行注釋 */
/*! 同樣是單行注釋 */
/** 這也是單行注釋，
* 第二行會(huì)接上第一行。
*/
例子
DocExample.h
#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>
@interface DocExample : 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
DocExample.m
#import "docExample.h"
@implementation DocExample
- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue{
UIColor *color = [UIColor colorWithRed:red green:green blue:blue alpha:1];
return color;
}
- (void)someMethod:(NSString *)str{
}
@end
最終效果
效果.png
編譯完成后Docset默認(rèn)會(huì)放在
~/Library/Developer/Shared/Documentation/DocSets/路徑下
閱讀文檔
Xcode-->Window-->Documentation And API Reference 找到你的工程名對(duì)應(yīng)的就是文檔
或者command+shift+0(零)
編譯完成后需要重啟Xcode才能看到，如果是初始工程的話，點(diǎn)擊了對(duì)應(yīng)文檔將會(huì)是空白，并且會(huì)跳轉(zhuǎn)到腳本寫的網(wǎng)址，手動(dòng)添加注釋之后就能看到文檔了。
利用Git部署文檔
1.拷貝文檔
在Git上新建一個(gè)倉庫,也可以在當(dāng)前倉庫上，將
~/Library/Developer/Shared/Documentation/DocSets/com.公司id.ScanIOSApp.docset/Contents/Resources文件下的html文件拷貝至Git倉庫的Master分支然后上傳。
2.獲取文檔訪問地址
找到當(dāng)前倉庫，找到Settings，下拉找到并設(shè)置如下
CEB36DEB-AB41-43A0-95BF-1EBAD3965D0A.png
3.將該地址添加到README.md中
[文檔](https://lengyi.github.io/Doc/)
3.點(diǎn)擊如圖顯示即可解決文檔共享的問題。
0E02B8F8-9000-460A-8D64-64E1CA273CC6.png
