使用AppleDoc快速生成iOS开发文档

需求

一个公司随着时间的推移会慢慢的成长起来，这也就意味着公司的队伍也会不断的壮大。在壮大的同时需要保证团队开发的规范性。这样有益于后期维护，同时也能够培养团队的协作能力。软件开发一直是公司的核心部门，那么作为 iOS开发部 的成员之一，就更应该积极做好各项工作。这次我就啰里啰嗦的整理一下网上的关于 AppleDoc 生成开发文档的相关知识点。此文章需要有一定的指令基础的童鞋学习，不然看了会比较吃力。有不懂的需要自行脑补一下，这里就不再累赘。

安装

打开终端，执行指令进行下载安装

$ git clone git://github.com/tomaz/appledoc.git
$ cd ./appledoc
$ sudo sh install-appledoc.sh

当出现 INSTALL SUCCEEDED 时说明成功了，你也可以用appledoc --version查看验证下。如果可以正常执行下面指令则证明安装成功，否则需要查看报错说明。

# 查看版本号
$ appledoc --version
# 查看更多文档信息
$ appledoc --help

查看版本号

使用

1. 使用终端进入代码目录

直接拖拽我们的工程文件夹到终端，然后按回车键
或者使用 cd+"项目名字目录"，然后按回车键
以上两种方法都可以进入到我们的工程根目录

2. 指令用法及参数说明

# 参考指令写法1(不生成docset文件)
$ appledoc --no-create-docset --output ./doc --project-name "QQ" --company-id "com.tencent.QQ" --project-company "Tencent Inc." /Users/superdanny/Desktop/QQ-Project/QQ/Views

# 参考指令写法2(不生成docset文件，参数使用“=”等号写法)
$ appledoc --no-create-docset --output="./doc" --project-name="QQ" --company-id="com.tencent.QQ" --project-company="Tencent Inc." /Users/superdanny/Desktop/QQ-Project/QQ/Views

# 参考指令写法3(生成docset文件并指定生成路径)
$ appledoc --output ./doc --project-name "QQ" --company-id "com.tencent.QQ" --project-company "Tencent Inc." /Users/superdanny/Desktop/QQ-Project/QQ/Views --docset-install-path ./doc

参数说明

参数	说明
--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 
@sa 
其中为：
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