代码注释可以让代码更容易接受和使用,特别是在大型项目合作开发或模块开发中。Objective-C中也有一些很方便的注释插件和文档生成工具。本文推荐两个开源软件:VVDocumenter注释工具和appledoc文档生成工具。

VVDocumenter

首先推荐一个Xcode插件VVDocumenter,它可以让我们在代码中快捷的插入通用的注释代码。

image

有了这个插件只需要在要注释的方法定义前输入三个斜杠(///),它就会自动为我们生成注释模板,这些注释模板可以用文档输出工具输出为说明文档。

下载和安装VVDocumenter

VVDocumenter插件是github上的一个开源项目,地址是https://github.com/onevcat/VVDocumenter-Xcode。你可以git clone或在github网站上下载工程的zip压缩文件。下载完成后,打开其中的工程,build&run一下就安装成功了。然后记得要重新启动一下Xcode应用,VVDocumenter插件就生效了。试试在方法定义前输入“///”。

appledoc

我们开发自己的模块时,经常会将模块接口提供给别人使用,这样我们不得不写一些接口说明文档。很多语言都提供了这种工具比如javadoc,doxygen等,可以将注释代码转化成在线文档。这里推荐一个特别适合Objective-C语言的一种文档输出工具appledoc。它可以把一些格式的注释转换成Apple SDK风格的文档,同时它支持VVDocumenter的输出注释格式。

安装appledoc

建议使用brew命令来安装,如果没有安装brew,可以先用一下命令安装一下:

1
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

然后执行brew安装命令来安装appledoc

1
brew install appledoc

使用appledoc生成文档

1
appledoc [OPTIONS] <paths to source dirs or files>

该命令将生成并安装文档到Xcode,可以通过Xcode的文档浏览器来查看文档,并可以在Xcode中搜索到相关接口。

image