需求
一个公司随着时间的推移会慢慢的成长起来，这也就意味着公司的队伍也会不断的壮大。在壮大的同时需要保证团队开发的规范性。这样有益于后期维护，同时也能够培养团队的协作能力。软件开发一直是公司的核心部门，那么作为 iOS开发部 的成员之一，就更应该积极做好各项工作。这次我就啰里啰嗦的整理一下网上的关于 AppleDoc 生成开发文档的相关知识点。此文章需要有一定的指令基础的童鞋学习，不然看了会比较吃力。有不懂的需要自行脑补一下，这里就不再累赘。
安装
打开终端，执行指令进行下载安装
|
|
当出现 INSTALL SUCCEEDED 时说明成功了，你也可以用appledoc –version查看验证下。如果可以正常执行下面指令则证明安装成功，否则需要查看报错说明。
|
|
使用
- 使用终端进入代码目录
直接拖拽我们的工程文件夹到终端，然后按回车键
或者使用 cd+”项目名字目录”，然后按回车键
以上两种方法都可以进入到我们的工程根目录 - 指令用法及参数说明
|
|
参数说明
| 参数 | 说明 |
|---|---|
| –no-create-docset | (选填参数)只生成html，不生成docset文件。如果需要生成，则去掉该参数即可 |
| –output | (必填参数)生成结果输出路径，如“./doc”，会在工程目录下创建一个doc文件夹存放生成的文档。当然你可以指定一个完整的目录路径存放生成的文档 |
| –project-name | (必填参数)工程名字，如“QQ” |
| –project-company | (必填参数)公司名字，如“Tencent Inc.” |
| –company-id | (选填参数)公司ID，如“com.tencent.QQ”，会生成文件名为companyID.projectName.docset的docset文件。如果不设置，则文件名为com.companyname.projectname.projectName.docset |
| –docset-install-path | (选填参数)生成docset文件的目录。如果此目录不设置，默认会在~/Library/Developer/Shared/Documentation/DocSets/目录生成 |
| /Users/superdanny/Desktop/QQ-Project/QQ/Views | 扫描对应路径下的类，如果想扫描当前目录所有文件，则将此路径换成.即可 |
如果是生成docset文件，则--output参数对应的目录会生成一个 docset-installed.txt 文件，里面记录docset存放的目录。
如果是不生成docset文件，则--output参数对应的目录会生成html文件。直接打开 index.html 文件即可查看。
支持的注释
下面是一些常用的语法示意:
单行注释
/// 这是单行注释。
/** 这也是单行注释 */
/*! 同样是单行注释 */
/** 这也是单行注释，
* 第二行会接上第一行。
*/
多行注释
/**
@brief 这里是方法的简介。仅对属性、方法有效，对类、协议 无效，会造成后续内容解析失败。所以该指令不能放到类注释里。
@param string 参数描述。
@return 返回值描述。
@exception NSException 可能抛出的异常。
@warning 这里是警告描述。
@bug 这里是缺陷描述。
@see 用它来指明其他相关的method或function。你可以使用多个这种标签。
@sa 同@see。
*/
注意事项
@brief、@see、@sa仅对属性、方法有效，对类、协议 无效，会造成后续内容解析失败。所以该指令不能放到类注释里。
@see <name>
@sa <name>
其中<name>为：
1) 当前类（或协议）中的属性或方法。（注意Objective-C方法签名的写法，一般为“方法名:参数1:参数2:⋯⋯”的格式）
2) 类（或协议）名。（注意AppleDoc不支持当前类）
3) 将@see或@sa指令放在注释的最后面，避免内容丢失
类注释
/** 第一行是类的简介
在简介的下面,就是类的详细介绍了。
没有间隔换行会被消除，就像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://superdanny.link
这个 [链接](http://example.net/) 会隐藏实际URL.
表格:
| header1(默认) | header2(居中) | header3(左对齐) | header4(右对齐) |
|---------|:-------:|:--------|--------:|
| normal | center | left | right |
| cell | cell | cell | cell |
引用:
这里会引用到方法 `pinyinFromChiniseString:`，这里会引用到类 `AreaListViewController`
这里会引用到一个代码块。具体办法是在每行内容的前面按tab键进行缩进，不然会无法正常识别。
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);
}
*/
最后我们来看看效果怎么样吧😁
再一次感谢您花费时间阅读这篇文章！
微博： @Danny_吕昌辉
博客： SuperDanny
