appledoc

appledoc是在stackoverflow上被大家推荐的一个注释工具。有几个原因造成我比较喜欢它：

1. 它默认生成的文档风格和苹果的官方文档是一致的，而doxygen需要另外配置。
2. appledoc就是用objective-c生成的，必要的时候调试和改动也比较方便。
3. 可以生成docset，并且集成到xcode中。这一点是很赞的，相当于在源码中按住option再单击就可以调出相应方法的帮助。
4. appledoc源码在github上，而doxygen在svn上。我个人比较偏激地认为比较活跃的开源项目都应该在github上。
5. 相对于headerdoc，它没有特殊的注释要求，可以用/** */ 的格式，也可以兼容/*! */的格式的注释，并且生成的注释有汇总页面。

安装

那么简单介绍一下如何安装appledoc，安装非常简单，只需要2步：

1
2
3

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

使用

介绍

为了使代码便于阅读，或者所写的代码需要提供给别人使用，这时就需要文档了。而就我们程序员来说，最好的方式莫过于将文档和源码放在一起，在写代码时通过一定的规范编写注释，然后通过工具可以将专门的注释部分抽取出来形成文档，类似的，JAVA语言就自带了javadoc命令。objective-c也中也有相应的工具，经过比较，最终选择了appledoc来做注释工具。appledoc的优点有不少，比如注释风格自由，生成的文档风格与苹果官方文档是一致的，而且可以生成docset，并且集成到xcode中去，也就是说，可以在源码中按住option键单击来调出相应方法的帮助。

appledoc的详细资料，可以参考官方文档。点击这里

安装

appdoc的安装非常简单，依次执行下面代码即可。

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

使用

注释格式

我所用的注释格式。注：appledoc的注释内容中，支持基本markdown语法

类和类的成员变量说明：

/**
这里写内容
*/

函数注释：

/**
这里写主要说明（下面空一行之后可以写详细说明）

这里写详细说明

@param 参数1 参数1说明
@param 参数2 参数2说明

@return 返回内容说明
*/

生成文档命令

进入到工程根目录，执行下面命令：

appledoc \                                   
--project-name XXX \
--project-company "XXX" \
--company-id XXX \
--output /tmp/doc \
./Core

其中，XXX 的内容根据具体情况填写，--output 后面接的是文档输出路径，最后一个路径，是需要生成文档的源代码所在路径。

默认情况，在生成docset文档后，appledoc会把生成的html以及中间文件删除，然后将生成的docset文档放置到xcode搜索的文档路径下。若要保存文档生成过程的中间数据比如生成的html文件，只需在上面的命令中增加以下参数即可。

--keep-intermediate-files

以下部分为原创:

如何生成文档，最主要的是配置一个output的路径和input的路径；output路径可以任意指定；input路径是你需要生成appledoc的文件们所在的文件夹路径.

输入命令如上；其中/tmp/doc为output的设置路径,/Core是input路径；在实际操作时可以将路径所在的文件夹拖到终端里，文件夹的路径就会被自动输入到终端里。

生成文档后，在output路径下是一个包含有实际文件路径的txt，通过它你就可以找到所生成的appledoc的全部内容。

未完待续