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

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

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

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

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

2. Xcode代码导出注释实践

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

• 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

我这边版本如下：

Snip20170320_3.png

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

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

Snip20170320_2.png

我从网上找到答案的主要意思（有很多是相关的，具体的答案真没找到）：

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

7. 解决方法

说了这么多，下面说一下解决方法：

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

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

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

Snip20170320_5.png

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

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