使用AppleDoc自动生成项目文档（XCode8）
总体效果及语法
AppleDoc可以根据项目中的注释自动生成类似于Apple官方文档的文档文件，大致的效果类似于这样：
文档总目录
展开样式
效果看上去还算不错，但是AppleDoc还是有一些限制的，就是要在代码中加上注释，而且只支持/**/、///、//等格式，不支持#pragma mark - WKNavigationDelegate。
appledoc 支持的注释类型
/// 这是单行注释。
/** 这也是单行注释 */
/*! 同样是单行注释 */
/** 这也是单行注释，
* 第二行会接上第一行。
*/
/** 第一行是类的简介
在简介的下面,就是类的详细介绍了。
没有间隔换行会被消除，就像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
Github链接：https://github.com/tomaz/appledoc
安装
git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh
完成后可以用appledoc --version验证下。
验证
使用
首先cd到你的项目文件夹下。
跑一下下面的命令，默认会编译出docset并安装进Xcode。
appledoc --project-name 你的项目名称 --project-company 你的公司名称 ./
然后你的项目文件夹中就会出现这样一个文件
文件
其次将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}"
最后选择这个target编译下就好了
编译
ps:如果这一步有出错，就退出xcode再编译一次就好了。
生成的目录包就在刚才的docset-installed.txt中
结果
结果
结果
好了，以上就是全部过程，还是挺方便的。
总结
能够根据注释自动生成类似于apple官方文档的功能固然很强大，但是对开发人员来说，还是直接看自己的注释来的实在方便。
不过，如果需要给CTO或者老板一份代码报告的话，用这个工具还是很方便（装X）的。O(∩_∩)O
自己工程遇到的执行错误
错误信息一： appledoc[13824:658676] * Assertion failure in +[GBMethodData methodDataWithType:result:arguments:], /Users/admin/Desktop/Git/appleDoc/Model/GBMethodData.m:44
此处代码以及解决方法：
+ (id)methodDataWithType:(GBMethodType)type result:(NSArray *)result arguments:(NSArray *)arguments {
//NSParameterAssert([arguments count] >= 1); //注释掉断言，重新执行安装脚本，强行走下去
return [[self alloc] initWithType:type attributes:[NSArray array] result:result arguments:arguments];
}
错误信息二：
return 2，调查没有找到对最后生成文档有什么影响。
备注：
appledoc不支持swift，不能显示swift中的注释信息等
appledoc只显示含有注释的property，method，如果该类没有注释信息，将不会生成该类对应的说明文档
