安装
- mac终端使用以下命令下载工具源码
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
- 安装成功提示如下
** INSTALL SUCCEEDED **
生成API文档
首先建一个Demo工程名称叫TestAppleDoc
- 终端命令生成
cd xxx/TestAppleDoc
appledoc --project-name 工程名称 --project-company lengyi(公司名称) ./
- 项目工程添加脚本自动生成 （方便更新文档）
1、选中项目，点击Add Target按钮，选择Cross-platform --> Aggregate
2、点击Add Build Phase 按钮，添加一个Run Script
3、添加下面的脚本代码,把前面几行改成自己的
4、在Xcode左上角选中新建的Target,然后build
5、文档就会编译好并自动安装进Xcode （每次编译问需要重启Xcode才能看到最新的文档）
#appledoc Xcode script
# Start constants
company="lengyi";
companyID="com.公司id";
companyURL="http://公司网址";
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
语法
文档中的注释只有符合规范，才能被appledoc认可，凡是以 "///"、 "/*"、 "/!"开头的注释都算是appledoc注释
/// 这是单行注释。
/** 这也是单行注释 */
/*! 同样是单行注释 */
/** 这也是单行注释，
* 第二行会接上第一行。
*/
例子
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 这里是警告,会显示成蓝色的框框
@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
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默认会放在
~/Library/Developer/Shared/Documentation/DocSets/路径下
阅读文档
Xcode-->Window-->Documentation And API Reference 找到你的工程名对应的就是文档
或者command+shift+0(零)
编译完成后需要重启Xcode才能看到，如果是初始工程的话，点击了对应文档将会是空白，并且会跳转到脚本写的网址，手动添加注释之后就能看到文档了。
利用Git部署文档
1.拷贝文档
在Git上新建一个仓库,也可以在当前仓库上，将
~/Library/Developer/Shared/Documentation/DocSets/com.公司id.ScanIOSApp.docset/Contents/Resources文件下的html文件拷贝至Git仓库的Master分支然后上传。
2.获取文档访问地址
找到当前仓库，找到Settings，下拉找到并设置如下
CEB36DEB-AB41-43A0-95BF-1EBAD3965D0A.png
3.将该地址添加到README.md中
[文档](https://lengyi.github.io/Doc/)
3.点击如图显示即可解决文档共享的问题。
0E02B8F8-9000-460A-8D64-64E1CA273CC6.png
