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

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

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

经过查找,比较大众的有三个:

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

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

appledoc: Github地址 ,适于生成html文档和xcode帮助文档(docset)。可以兼容 /** */格式,也可以兼容 /*! */格式的注释。

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

appledoc的安装

第一种:打开终端,输入以下命令:

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

appledoc的使用

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

111608265-54c02d5dfefe5185

ViewController.h
121608265-1b5ceeb31f275a8e

ViewController.m

然后演示appledoc的使用:

1.在终端中使用

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

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

具体过程如下:

131608265-38d08feeb2bd337c

生成Docset

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

141608265-75315ae0d0d5293b

doc目录

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

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

151608265-3b0a83b380a0550e

在Xcode中查看

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

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

161608265-4f6f78eb9d0d3911

html文档

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

2.在Xcode里使用

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

171608265-dc46a5c77a483ecc

创建Target

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

181608265-bdce67e2e0fae042

添加script

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

编译生成文档

注释样式

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

在Xcode里面,我们可以用command + option + /方便快捷地生成注释,很方便。大家可以多尝试尝试各种注释。更多的注释格式可以看这里

 

1 收藏 评论

相关文章

可能感兴趣的话题



直接登录
跳到底部
返回顶部