03-开源框架:Appledoc【oc代码转文档】

引言:

appledoc是一个可以帮你生成Objective-C代码注释的辅助工具,appledoc所生成的注释API文档与苹果类库的API文档保持一致.

这可以让Xcode能够识别出我们自己的API文档.


参考:

1:Mac安装Brew

http://blog.csdn.net/chenyi8888/article/details/7345113

2:使用Objective-C的文档生成工具:appledoc

http://blog.devtang.com/blog/2012/02/01/use-appledoc-to-generate-xcode-doc/

Mac安装Brew

sudo brew install wget  

卸载的话，命令如下：
sudo brew uninstall wget

查看安装软件的话，命令如下：
sudo brew search /apache*/

注意/apache*/是使用的正则表达式，用/分割。


安装:

appledoc的Github托管地址如下:

https://github.com/tomaz/appledoc

此版使用Brew安装appledoc

命令:sudo brew install appledoc

如果你事先没有安装Brew,那么上面的命令肯定也就失效了.

安装Brew使用如下命令:

命令:curl -LsSf http://github.com/mxcl/homebrew/tarball/master | sudo tar xvz -C/usr/local --strip 1

注意上面命令中红色标识的路径.

你应该检查一下,你是否有这个路径,如下图所示:


如果没有,就手动创建一个以后,在执行安装Brew的命令.


检测一下Brew是否安装成功.

命令:brew

如果出现一堆brew的使用说明,那么说明已经安装成功了.

接下来回到我们的appledoc 运行以下命令:

命令:sudo brew install appledoc

在执行命令中,还是有可能失败.原因是指定的路径没有足够的读写权限.

/usr/local/bin is not writable. You should change its permissions.

那么去红色标识的路径中为其设置读写权限


完成后,此时卸载appledoc. 此时appledoc安装了一半,没有完全安装成功.

命令:brew uninstall appledoc

结束后,再重新执行一次安装.


不出意外的话,应该就安装成功了.

然后同样的检测一下,是否安装成功,调出appledoc的帮助文档.

命令:appledoc --help





使用:

通过以下命令来生成API文档

[csharp] view plaincopy
  1. appledoc --project-name yushuyi12345677     
  2.          --project-company "xiaoyu123"   
  3.          --company-id aaaa    
  4.          --output /Users/yushuyi/Desktop       
  5.          /Users/yushuyi/Desktop/MultiFTPTask/MultiFTPTask/Classes  

注:以上命令中分别需要提供5个参数,分别是:

1:工程名称

2:公司名称

3:工程ID

4:生成结果输出路径

5:扫描哪个路径下的类.

该命令会根据指定的路径将所有的的类遍历一次,当生成成功以后,appledoc会新建一个文本文件来记录生成情况,这个文件存放在上面命令中指定的--output.

执行上面的命令时,请确保删去了所有的换行符以后在执行.

生成的文档会自动存放在Xcode默认的文档目录里: 

~/Library/Developer/Shared/Documentation/DocSets

不出意外的话,进入到目录里面就可以看到刚刚执行命令以后生成的文档:



我们都知道按住option键位时,再点击某个方法或者属性名称


 

使用Objective-C的文档生成工具:appledoc

Feb 1st, 2012

前言

做项目的人多了，就需要文档了。今天开始尝试写一些项目文档。但是就源代码来说，文档最好和源码在一起，这样更新起来更加方便和顺手。象Java语言本身就自带javadoc命令，可以从源码中抽取文档。今天抽空调研了一下objective-c语言的类似工具。

从stackoverflow 上找到三个比较popular的工具：doxygen, headdoc和appledoc 。它们分别的官方网址如下：

介绍

我把这3个工具都大概调研了一下，说一下我的感受。

docxygen

docxygen感觉是这3个工具中支持语言最多的，可以配置的地方也比较多。我大概看了一下文档，觉得还是比较复杂，而且默认生成的风格与苹果的 风格不一致。就去看后面2个工具的介绍了。另外，它虽然是开源软件，但是没有将源码放到github上让我感觉这个工具的开发活跃度是不是不够。

headerdoc

headerdoc是xcode 自带的文档生成工具。在安装完xcode后，就可以用命令行：headdoc2html + 源文件名 来生成对应的文档。我个人试用了一下，还是比较方便的，不过headerdoc的注释生成规则比较特别，只生成以 /*! */ 的格式的注释。还有一个缺点是每个类文件对应一个注释文件，没有汇总的文件，这点感觉有点不爽。

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

使用

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

1

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

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

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

 

使用：

前往文档中的路径

打开：


posted on 2015-04-30 13:32  袁晓俊  阅读(412)  评论(0)  编辑  收藏  举报

导航