appledoc导出iOS代码文档的使用和问题详解(干货篇)


appledoc导出iOS代码文档的使用和问题详解(干货篇)

1. 简单说一下背景和自己感受

背景:
项目好像突然黄了,公司让详细写项目代码的注释并且导出文档,弄完之后就要封版。

说实话:听到这个消息之后心里还是很担心的,因为我知道公司不可能养闲人,我手上的项目本来年后就没有什么起色,加上突然来了这样的一个‘噩耗’,顿时就知道后面肯定没好事

我知道公司不会养闲人,所以在这几天项目闲下来的日子里,忐忑过,也想到了项目可能面临的种种,当然也包括自己所可能受到的种种影响。但是毕竟我们只是听上面安排的一线开发人员,做不了项目大方向的主,只能服从安排,所以不管心情如何还是要把工作完成,只是想记录一下心情和工作中遇到的问题。

2. Xcode代码导出注释实践

Xcode导出代码文档的方式一共有三种,Doxygen, headdoc 和 appledoc 。以下是三者官网链接:

3. 介绍appledoc

由于我查到的资料显示appledoc最受欢迎,并且生成的文档风格和apple一致,非常满足我的需求,故我使用的也是appledoc,有兴趣的同学可以自行进入官网或网页自行查询。

appledoc的几点优点:

  • 它默认生成的文档风格和苹果的官方文档是一致的,无需额外配置。
  • appledoc 就是用 objective-c 生成的,必要的时候调试和改动也比较方便。
  • 可以生成 docset,并且集成到 Xcode 中。这一点是很赞的,相当于在源码中按住 option 再单击就可以调出相应方法的帮助。

4.安装appledoc

安装appledoc步骤非常简单,只需两步:

  1. 终端中clone项目到本地
  2. 运行安装脚本
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

验证是否安装成功

appledoc --version

我这边版本如下:

 

5.使用

appledoc的使用非常简单,2步即可:

  1. 在终端中进入要导出文档的目录下
  2. 输入如下命令
appledoc --project-name "XYBannerView" --project-company "xiaoyouPrince" ./

注意:

  1. XYBannerView:是你自己的项目名(随便写也可以)
  2. xiaoyouPrince: 是项目对应的公司名(随便写也可以)
  3. ./ 导出到当前路径的一个参数,前面要有空格!

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

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

6.我遇到的问题:Command /bin/sh failed with exit code 250

报错信息:

Command /bin/sh failed with exit code 250

如图:(遇到的同学肯定印象深刻,并且还很难找到答案,这也是我为什么想写这个文章的原因)

 

我从网上找到答案的主要意思(有很多是相关的,具体的答案真没找到):

  1. 和 enum 和 NS_ENUM 类型的支持有关(这个在作者的更新中已经修改好像)
  2. 和 Pods 中的三方库等资源有关。由于项目大很多东西是不支持的
  3. 警告一般是项目中的注释,缺少参数或格式问题(三方库中尤其明显)

7. 解决方法

说了这么多,下面说一下解决方法:

由于三方库和一些资源有问题,那就跳过三方(Pods和一些手动导入的),进入下一层目录执行命令

appledoc --project-name "XYBannerView" --project-company "xiaoyouPrince" ./

这就对于项目中文件结构的分层很重要,我们自己的代码和项目中引用的三方代码需要分开

 


虽然还是有些警告和小问题,但是可以导出来了。

我有些问题并没有研究很深入,希望有研究的朋友能不吝赐教,多多分享!

 

posted @ 2017-03-20 21:36 xiaoyouPrince 阅读(...) 评论(...) 编辑 收藏