如何将自己项目的代码文档导出为苹果样式

2017-06-21 | 阅读：次

代码技术文档

代码技术文档是很多大公司的必做工作，这一步如果做得好，在后续的开发迭代中会少出现许多bug，而且不管开发人员如何迭代，都能快速地上手新项目，这样就能无形当中降低公司的成本。磨刀不误砍柴工，这个道理谁都懂。但是很多小公司或者是程序员可能会怕麻烦，增加工作量，便不去做这个东西，这就导致了很多小公司两三个或三四个人去维护一个项目，在每次更新迭代的时候都会出现同样的bug或者问题，或者是有人员流动的时候，新入员工需要花大量时间去阅读了解代码，后期还不一定会避免一些老的低级bug。表面上节省了文档编写的时间，但后续为此付出代价的时间比编写时间多许多。还有一种情况是上面英文文章中提到的，就是你如果在App Store上上线了一个APP，然后你需要做其他工作，几个月后你需要给该APP更新一下版本，那时候你再看代码想下手，肯定以为是别人写的，但如果有文档，工作肯定事半功倍了。

本文将展示如何为一个项目做一个基于web的代码文档。

beging

新建一个oc工程，工程名后面会用到，DEMO地址

文档标注

最简单的标注就是双斜杠：

//标注说明的内容

这种方法也是大家最经常用的，简单方便。如果说对于文档或者整个项目而言，就没有太大用处了，只是说你去仔细看某个类的时候会对你的理解有帮助。

这里说的代码文档是指使用Xcode能很好的识别，看文档的人也能快速理解，Xcode是支持编程者使用特定的关键字，也叫标记，来对代码进行标注的。高效的标注几个基本要求如下：

1.Utilities面板的Quick Help Inspector会显示标注 2.当你按下Option键然后点击备注的方法、类或属性名时弹出的帮助菜单 Help Popup 里 3.在代码提示的弹框里面会显示注释信息

但在Xcode中使用 (⌥ Option + ⌘ Command + /)的组合键快速注释，有参数或者返回值的Xcode会自动识别并帮你添加@param或@return关键字，最牛逼的是注释支持markdown语法，你想怎么描述就怎么描述。

photos

再介绍其他两个关键字@code ... @endcode和@remark，前者是代码标签，可以放一小段代码用于提示等，后者是加粗重点提示。他们在你用option点击查看的时候才会看到，都是跟在属性说明或者方法说明后面。

加上这些关键词后，在使用该方法时，option加单击该方法你就能看到如下图的注释了

photos

这里快速分享其他类型的文档注释关键词(具体使用见DEMO)：

@class: 后面跟类名，类的描述
@interface: 同上
@protocol: 同上，需跟协议名，协议的描述
@superclass: 本类的父类
@classdesign: 本类使用中需要特别注意的事项，如是单例类
@coclass: 合作开发的类
枚举这里就不讲了，去看demo吧,其他还有一些未涉及的注释希望读者也发掘发掘，并告诉我一下，共同学习

导出为基于web样式的代码文档

1.首先是安装jazzy：

sudo gem install jazzy

输入密码后等待安装成功，如果安装不成功，你就得去查查gem版本或ruby环境了，自己google。

2.使用

安装成功后cd到所需工程目录下，按顺序输入以下代码，选填表示不是必须输入：

jazzy \
 --objc \
 --author Joshpell（选填） \
 --author_url 你的个人网站地址（选填） \
 --module-version 1.0.0（选填） \
 --umbrella-header PrefixHeader.pch（将你的所有需要文档化的头文件都放pch文件中，这里pch文件是相对路径） \
 --framework-root . \
 --output （文档输出相对路径，一般是工程文件夹新建一个docs：工程相对路径/docs） 

输入完成，回车，等待片刻即可。成功后工程文件夹会多一个docs文件夹，打开index.html就可以浏览你的代码文档了，如图：

photos

jazzy默认支持swift，如果你是swift项目，恭喜你了，cd到工程目录下，一行代码搞定(感觉OC受到了歧视。。。)：

jazzy --min-acl internal

如果你是特定版本的swift，可能会看不到jazzy输出，就只能用特定版本的命令输出：

jazzy --swift-version x.x.x --min-acl internal--

如果你想像OC一样加入更详细的文档描述，参考下面命令：

jazzy \
  --clean \
  --author Realm \
  --author_url https://realm.io \
  --github_url https://github.com/realm/realm-cocoa \
  --github-file-prefix https://github.com/realm/realm-cocoa/tree/v0.96.2 \
  --module-version 0.96.2 \
  --xcodebuild-arguments -scheme,RealmSwift \
  --module RealmSwift \
  --root-url https://realm.io/docs/swift/0.96.2/api/ \
  --output docs/swift_output \
  --theme docs/themes

有一点是非常牛逼的，你导出的文档它会自动生成一个swift代码版本的参照！ DEMO地址，如果觉得对你有帮助别忘了star一个，共同学习，共同进步！

这里再推荐一下唐巧推荐的几个工具;

参考Documenting Your Objective-C and Swift Code in Xcode with HeaderDoc and Doxygen