Xcode8 利用appledoc 自动生成项目文档
最近写了一个小项目，想做完善点，就想到要有一个API的文档。知道有很多工具可以自动生成，但是具体一直没实现过，正好利用这个机会实验一把。
刚开始搜索了下，基本锁定有这两种工具:
-
HeaderDoc 是苹果官方的文档生成工具。好处是Xcode自带了，生成的文档风格和Apple官方的保持一致，支持的语言比较多。缺点是可调教的地方比较少，注释的风格要求比较严格等；貌似除了Apple外，其他使用的人比较少；最主要的是很多博文里链接到官方的地址都不存在了
-
appledoc 是比较专一的，只为Objective-C服务，能生成和Apple一个风格的文档，功能齐全，使用方便，可以直接编辑成docset安装进Xcode。缺点是支持的语言少。
最终我决定使用appledoc生成
安装 appledoc
git clone git://github.com/tomaz/appledoc.git
cd ./appledoc
sudo sh install-appledoc.sh
安装完验证一下版本OK了
appledoc --version
生成API文档
这里说两种方法：
- 终端命令生成
cd到你项目所在的目录，然后再运行下面命令，然后就编译出docset并安装进Xcode。注意下面替换成你的工程名称和公司名称
appledoc --project-name 工程名称 --project-company 公司名称 ./
- Run Script 集成在项目内
这个方法就是把生成方式放在项目内啦，方便更新文档而已。缺点是得为每个项目添加，看个人情况使用吧。
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="公司名称";
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}"
语法
首先，文档中的注释只有符合规范，才能被appledoc认可
凡是以"///"、"/*"或"/!"开头的注释块，都算是appledoc注释。下面是实例：
///这是单行注释
/** 这也是单行注释/
/*！ 这也是单行注释/
/** 这也是单行注释，
* 第二行会接上第一行
*/
注释块中,每一行的开头的空格和“*”字符多数情况都会被appledoc忽略。
连续的两行（即没有间隔空行）的注释，将被合并成一个段落，并忽略换行，就想html。
在注释块中，appledoc支持如下语法：Markdowm、HTML、HeaderDoc Tags。
- Markdown的语法在这里中文翻译介绍,比较简单，学习成本不高，简书写博文不就是这个嘛，大家可以学习一下。
- HTML 略。喜欢的直接码HTML吧
- HeaderDoc Tags 这个是苹果官方的，也是我们常用的了。例如：@param、@return、@warning酱紫的东西。官方文档我也没找到，找到的童鞋麻烦告诉我，多谢。不过貌似appledoc对这个的支持也不完美。
下面是一些大家都可以搜到的语法示意啦：
///这里是属性的说明
@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
最后
编译完成的Docset默认会放在/Users/用户名/Library/Developer/Shared/Documentation/DocSets路径下
阅读在Xcode --> Window-->Documentation And API Reference 里面找啦，快捷键就是command+shift+0
