iOS - Xcode 自动生成注释文档

介绍

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

• docxygen
• headdoc
• appledoc

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

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

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

Terminal

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

使用

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

Terminal

# 参考指令写法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 文件即可查看。