Objective-C 自动生成文档工具:appledoc

来源：iOS_小松哥 

www.jianshu.com/p/fd4d8d6b6177

如有好文章投稿，请点击 → 这里了解详情

由于最近琐事比较多，所以好久没有写文章了。今天我们聊一聊Objective-C自动生成文档。

做项目的人多了，就需要文档了。手工写文档是一件苦差事，但是我们也有从源码中抽取注释生成文档的专用工具。

经过查找，比较大众的有三个：

doxygen：适于生成html文档与pdf文档。 支持的语言多，可以配置的地方也比较多。默认生成的风格与苹果的风格不一致。

headdoc ：是 Xcode 自带的文档生成工具。在安装完 Xcode 后，就可以用命令行来生成对应的文档。不过它只生成以/*! */的格式的注释。不兼容 /** */格式的注释

appledoc: Github地址 https://github.com/tomaz/appledoc，适于生成html文档和xcode帮助文档（docset）。可以兼容 /** */格式，也可以兼容 /*! */格式的注释。

我感觉appledoc是最好的，所以在这里，我只介绍一下appledoc的使用，有兴趣的童鞋也可以研究下其他两种。

appledoc的安装

第一种：打开终端，输入以下命令：

git clone git://github.com/tomaz/appledoc.git

cd appledoc

sudo sh install-appledoc.sh

第二种：如果你装了homebrew，打开终端，输入以下命令：

brew install appledoc

appledoc的使用

为了演示appledoc的使用，我在桌面新建了一个工程Test，然后在ViewController类里面加了一些注释：

ViewController.h

ViewController.m

然后演示appledoc的使用：

1.在终端中使用

使用 appledoc 时，打开终端，进入项目所在目录，使用如下命令即可：

appledoc --output 输出路径 --project-name 工程名 --project-company 公司名 --company-id 公司ID .

例如我在这里使用的命令是：

appledoc --output ./doc --project-name Test --project-company lisong --company-id lisong .

具体过程如下：

生成Docset

appledoc 会扫描当前路径下的所有文件，然后生成好文档放到 doc 目录下。

doc目录

编译出的Docset

默认会放在~/Library/Developer/Shared/Documentation/DocSets路径下，里面包含html的文档。首先显示生成的Docset的包内容，然后在Contents/Resources/Documents路径下，双击打开里面的index.html可以在浏览器中查看文档了。

并且生成的Docset已经安装到Xcode中。重启Xcode后，在Help—Documentation and API Reference菜单下也可以看到生成的文档：

在Xcode中查看

如果不想生成Docset，而是想生成html，就需要加一个--no-create-docset，这里我使用命令：

appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .

则会在doc目录下生成一个html文件夹，也是双击里面的index.html就可以在浏览器中查看文档了。

html文档

你也可以在终端用appledoc --help查看所有可用的参数。详细的信息可以查看官方的文档：http://gentlebytes.com/appledoc/

2.在Xcode里使用

1.首先创建一个Aggregate类型的Target，取名Document

创建Target

2.选择Build Phases，点击左边的小加号，选择New Run Script Phase，建好了以后打开刚刚建立的Run Script，在框里输入命令，命令与终端一样，这里我们输入：

appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .

添加script

3..然后点左上角选择Document，编译一下，成功后文档就生成在doc目录下了。

编译生成文档

注释样式

因为appledoc是通过注释生成文档的，下面说说注释的样式，几种常见的有：

/// Single line comment.

 

/// Single line comment spreading

/// over multiple lines.

 

/** Single line comment. */

 

/*! Single line comment */

 

/**

* Single line comment spreading

* over multiple lines.

*/

 

/**

Single line comment spreading

over multiple lines. No star

*/

在Xcode里面，我们可以用command + option + /方便快捷地生成注释，很方便。大家可以多尝试尝试各种注释。

更多的注释格式可以看这里：https://github.com/tomaz/appledoc/blob/master/CommentsFormattingStyle.markdown