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

0.144字数 570阅读 113

需求

一个公司随着时间的推移会慢慢的成长起来,这也就意味着公司的队伍也会不断的壮大。在壮大的同时需要保证团队开发的规范性。这样有益于后期维护,同时也能够培养团队的协作能力。软件开发一直是公司的核心部门,那么作为 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+"项目名字目录",然后按回车键
以上两种方法都可以进入到我们的工程根目录

  1. 指令用法及参数说明
# 参考指令写法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 <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

推荐阅读更多精彩内容

  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
  • linux资料总章2.1 1.0写的不好抱歉 但是2.0已经改了很多 但是错误还是无法避免 以后资料会慢慢更新 大...
  • pdf下载地址:Java面试宝典 第一章内容介绍 20 第二章JavaSE基础 21 一、Java面向对象 21 ...
  • 记录时间:2018年1月4日 记录地点:湖南长沙 http://www.meipai.com/media/9472...
  • 一、Dispatch Queue 二、基本概念:异步 同步 串行队列 并发队列 三、dispatch_set_ta...