iOS - Xcode 自动生成注释文档

介绍

自动生成注释文档有三种方式:

docxygen
docxygen 感觉是这 3 个工具中支持语言最多的,可以配置的地方也比较多。我大概看了一下文档,觉得还是比较复杂,而且默认生成的风格与苹果的风格不一致。就去看后面 2 个工具的介绍了。另外,它虽然是开源软件,但是没有将源码放到 github 上让我感觉这个工具的开发活跃度是不是不够。

headerdoc
headerdoc 是 xcode 自带的文档生成工具。在安装完 xcode 后,就可以用命令行:headdoc2html + 源文件名 来生成对应的文档。我个人试用了一下,还是比较方便的,不过headerdoc的注释生成规则比较特别,只生成以 /! / 的格式的注释。还有一个缺点是每个类文件对应一个注释文件,没有汇总的文件,这点感觉有点不爽。

appledoc
appledoc 是在 stackoverflow 上被大家推荐的一个注释工具。比起以上两个工具,他的优点有:
它默认生成的文档风格和苹果的官方文档是一致的,而 doxygen 需要另外配置。
appledoc 就是用 objective-c 生成的,必要的时候调试和改动也比较方便。
可以生成 docset,并且集成到 xcode 中。这一点是很赞的,相当于在源码中按住 option 再单击就可以调出相应方法的帮助。
appledoc 源码在 github 上,而 doxygen 在 svn 上。我个人比较偏激地认为比较活跃的开源项目都应该在 github 上。
相对于 headerdoc,它没有特殊的注释要求,可以用/* / 的格式,也可以兼容/! /的格式的注释,并且生成的注释有汇总页面。

appledoc 的安装

那么简单介绍一下如何安装 appledoc,安装非常简单,只需要 2 步:

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

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

Terminal
1
2
3
4
# 查看版本号
$ appledoc --version
# 查看更多文档信息
$ appledoc --help

使用

1、使用终端进入代码目录
直接拖拽我们的工程文件夹到终端,然后按回车键
或者使用 cd+”项目名字目录”,然后按回车键
以上两种方法都可以进入到我们的工程根目录
2、指令用法及参数说明

Terminal
1
2
3
4
5
6
7
8
# 参考指令写法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
# 以上都是扫描指定目录下的文件,如果想扫描当前目录所有文件,只需要将指定目录换成"."即可
$ appledoc --no-create-docset --output="./doc" --project-name="QQ" --company-id="com.tencent.QQ" --project-company="Tencent Inc." .

参数说明

参数 说明
–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 文件即可查看。

------本文结束 感谢阅读------

本文地址:http://kaaaaai.cn/articles/automatically-generates-annotation-documents.html
本文基于 知识共享署名-相同方式共享 4.0 国际许可协议发布
转载请注明出处,谢谢!

众筹项目:拯救世界!
0%