Leon’s Blog

Dreams don't work unless you do.

AppleDoc自动生成文档

当项目不断扩大,团队中不断有新的成员加入,这时候就需要我们的项目有可查看的技术文档,方便新加入的成员查阅,快速地了解项目。但是这种文档如果从团队中专门调配出人去整理的话,既低效成本又高,还好iOS也有类似于java语言中的javadoc可以根据源码中的注释来生成技术文档的工具。

目前iOS比较常用的自动生成文档工具有doxygen, headdoc 和 appledoc三个,下面来看一下这三个工具的对比情况。

Doxygen

Doxygen原本是为C++开发的文档生成工具，当然它是开源的，通过一票扩展也能支持各种主流非主流语言。除了能生成HTML外，还能生成pdf和LATEXLATEX格式。在appledoc出现之前，很多人就喜欢用这个来生成ObjC代码的文档。相比HeaderDoc来说，有很多可以调教的地方。苹果官方也曾为这个工具写过文档。一切看上去都很棒，不足的地方就是，它生成的文档风格和官方文档的风格差了很多（虽然说不算太难看，但是放到Xcode里看格格不入），配置复杂等。。

HeaderDoc

HeaderDoc是苹果官方的文档生成工具。支持JavaDoc风格的注释，支持一些比较常见的语言，例如Java、C/C++、ObjC、Python、Ruby等等。 官方的好处就是：安好Xcode就自带了，生成的文档风格和Apple官方保持一致，支持语言较多。缺点就是可调教的的地方较少，不生成聚合页，注释风格要求较严等。

appledoc

appledoc是最年轻的一个，并且只为Objective-C服务（很专一），能生成和Apple一个风格的文档，功能齐全，使用方便，还可以直接编译成docset安装进xcode。。看样子除了语言支持太少，其他的表现都不错，关键是最贴合Xcode。 虽然没有统计数据，但我相信ObjC这个用的人应该是最多的。

因为我们的项目是基于object-c去开发的,所以经过上面的对比,我更加青睐appledoc,接下来就让我们用appledoc来生成一份文档吧。

安装appledoc

方法一

终端命令

1
2
3
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

方法二

  1. 安装Homebrew
  2. 执行命令: brew install appledoc

验证是否安装:

1
appledoc --version

如果显示了版本号说明安装成功了,接下来就是用appledoc来生成文档了。

生成API文档

我们新建一个工程,在viewController中的.h中生成注释来测试。
既然我们使用的appledoc来生成API文档,那么注释方面也要符合appledoc的注释规范:

/// 这是单行注释。 (// 双斜杠这种单行注释是不会被识别的,在xcode中三斜杠的注释 按住option + function 会显示注释内容,双斜杠也是不会显示的)

/* 这也是单行注释 /

/! 同样是单行注释 /

/** 这也是单行注释，

  • 第二行会接上第一行。
    */

在注释块内，appledoc还支持Markdown、HTML、HeaderDoc Tags的语法。

比如我们在viewController.h中的注释是这个样子:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
/** 第一行是类的简介
 
 在简介的下面,就是类的详细介绍了。
 没有间隔换行会被消除，就像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://leonzlw.github.io/
 
 [这个](http://example.net/) 链接会隐藏实际URL.
 
 表格:
 
 | header1 | header2 | header3 |
 |---------|:-------:|--------:|
 | normal  |  center |  right  |
 | cell    | cell    | cell    |
 
 
 @since iOS5.0
 
 */
@interface ViewController : UIViewController

/// 这是属性说明
@property (nonatomic, copy) NSString *vcProperty;

/**
  这里是方法的使用说明,相当于(@discussion)

 @brief 这里是方法的简介。该Tag不能放到类注释里。
 @see initWithTitle: 用它来指明其他相关的 method 或 function。
 @param title 参数说明
 @return 返回参数说明
 */
- (instancetype)initWithTitle:(NSString *)title;

@end

接下来我们来生成如上所示的文档,有两种方式:

方法一

终端命令生成:进入项目的所在目录,然后运行下面的命令

1
appledoc --project-name 工程名称 --project-company 公司名称 --company-id 项目唯一标识 --output 生成结果输出路径 ./ 扫描哪个路径下的类(这里是当前目录下的所有类,包含子目录中的类)

最终会在output的目录中生成docset-installed.txt的文件,打开文件会有如下内容

1
2
3
4
Documentation set was installed to Xcode!

Path: /Users/用户名/Library/Developer/Shared/Documentation/DocSets/com.baidu.appledoc.AppleDoc.docset
Time: 2016-08-12 16:48:08 +0000

然后进入Path路径可以发现这个路径是官方API文档的下载目录,我们自己生成的API文档也在这里

.docset其实是一个bundle文件,我们选中自己生成的.docset文件显示包内容可以在Documents目录下看到.html文件。

打开.html文件就可以查阅我们生成的API文档啦~

方法二

集成到xcode工程:
1.新建Aggregate Target

2.添加脚本功能

3.把下面代码中company,companyID,companyURL,outputPath的值替换成你的信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
#appledoc Xcode script  
# Start constants  
company="公司名称";  
companyID="公司id";
companyURL="公司网址";
target="iphoneos";
#target="macosx";
outputPath="导出路径";
# 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}"

4.把修改后的脚本代码粘贴到下面的区域

5.xcode工程选中新生成的Target运行就会在outputPath路径中生成你的API文档了,在/Users/用户名/Library/Developer/Shared/Documentation/DocSets/ 中也会生成一份.docset文件。

除了通过.html文件查看API文档也可以通过Dash查看,非常方便哦~

参考:

iOS