1. 简单说一下背景和自己感受
背景：
项目好像突然黄了，公司让详细写项目代码的注释并且导出文档，弄完之后就要封版。
说实话：听到这个消息之后心里还是很担心的，因为我知道公司不可能养闲人，我手上的项目本来年后就没有什么起色，加上突然来了这样的一个‘噩耗’，顿时就知道后面肯定没好事
我知道公司不会养闲人，所以在这几天项目闲下来的日子里，忐忑过,也想到了项目可能面临的种种，当然也包括自己所可能受到的种种影响。但是毕竟我们只是听上面安排的一线开发人员，做不了项目大方向的主，只能服从安排，所以不管心情如何还是要把工作完成，只是想记录一下心情和工作中遇到的问题。
2. Xcode代码导出注释实践
Xcode导出代码文档的方式一共有三种，Doxygen, headdoc 和 appledoc 。以下是三者官网链接：
3. 介绍appledoc
由于我查到的资料显示appledoc最受欢迎，并且生成的文档风格和apple一致，非常满足我的需求，故我使用的也是appledoc，有兴趣的同学可以自行进入官网或网页自行查询。
appledoc的几点优点：
- 它默认生成的文档风格和苹果的官方文档是一致的，无需额外配置。
- appledoc 就是用 objective-c 生成的，必要的时候调试和改动也比较方便。
- 可以生成 docset，并且集成到 Xcode 中。这一点是很赞的，相当于在源码中按住 option 再单击就可以调出相应方法的帮助。
4.安装appledoc
安装appledoc步骤非常简单，只需两步：
- 终端中clone项目到本地
- 运行安装脚本
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh
验证是否安装成功
appledoc --version
我这边版本如下：
Snip20170320_3.png
5.使用
appledoc的使用非常简单，2步即可：
- 在终端中进入要导出文档的目录下
- 输入如下命令
appledoc --project-name "XYBannerView" --project-company "xiaoyouPrince" ./
注意：
- XYBannerView：是你自己的项目名（随便写也可以）
- xiaoyouPrince： 是项目对应的公司名（随便写也可以）
-
./导出到当前路径的一个参数，前面要有空格！
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
我从网上找到答案的主要意思（有很多是相关的，具体的答案真没找到）：
- 和 enum 和 NS_ENUM 类型的支持有关（这个在作者的更新中已经修改好像）
- 和 Pods 中的三方库等资源有关。由于项目大很多东西是不支持的
- 警告一般是项目中的注释，缺少参数或格式问题（三方库中尤其明显）
7. 解决方法
说了这么多，下面说一下解决方法：
由于三方库和一些资源有问题，那就跳过三方（Pods和一些手动导入的），进入下一层目录执行命令
appledoc --project-name "XYBannerView" --project-company "xiaoyouPrince" ./
这就对于项目中文件结构的分层很重要，我们自己的代码和项目中引用的三方代码需要分开
Snip20170320_5.png
虽然还是有些警告和小问题，但是可以导出来了。
我有些问题并没有研究很深入，希望有研究的朋友能不吝赐教，多多分享！
网友评论