xcode 自动添加注释，生成文档

一、自动生成注释代码

添加一个快捷键，生成注释代码

ThisService 下载连接：http://wafflesoftware.net/thisservice/

Doxygen.rb 下载连接：http://www.brokenrul.es/blog/wp-content/uploads/2011/03/Doxygen.rb_.zip

1、打开ThisService，进行以下配置

Name:右键菜单中的名字

Script:将Doxygen.rb拖拽到这里

2、打开系统偏好设置，找到键盘，进行以下配置

这里我将快速文档注释的快捷键设置成了Command + option + /

3、使用

选中需要注释的函数名，包括所有的参数，右键点击快速文档注释，或者直接按快捷键即可。

二、生成文档

生成文档有三种方式：

docxygen http://www.stack.nl/~dimitri/doxygen/index.html
headdoc http://developer.apple.com/opensource/tools/headerdoc.html
appledoc http://gentlebytes.com/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，安装非常简单，只需要2步：

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

 cd appledoc

 sudo sh install-appledoc.sh

使用

使用appledoc时，只需要用如下命令即可：

1	`appledoc -o ./doc --project-name ynote --project-company youdao .`

appledoc会扫描当前路径下的所有文件，然后生成好文档放到doc目录下。你也可以用appledoc –help查看所有可用的参数。

基本上使用起来还是比较方便的，详细的信息可以查看官方的文档：http://gentlebytes.com/appledoc/

Posted by 唐巧 Feb 1st, 2012 iOS, xcode