在Xcode8下文档化你的Objective-C代码

苹果在Xcode8为了安全性和稳定性，禁用第三方插件。
第三方注释插件VVDocumenter虽然不能在Xcode8上继续使用，但所幸苹果在此插件基础上提供了快熟注释的功能。

Xcode8 注释

在Xcode8上可以通过快捷键 (⌥ Option + ⌘ Command + /) 添加注释。
格式为 /** … */ ：

.m方法注释

下面看下带不同标签的注释

@return
返回参数

返回参数

@param
参数

参数

多个参数

@code ... @endcode
代码标签

@remark
粗体提醒

标签

我们做注释是为了能够输出有效的文档，方便查询。
市面上有不同插件可以输出文档，但各自的识别格式、标签和输出的风格大不相同。
这次我们用Jazzy插件来进行文档化注释，Jazzy不识别@code和@remark ，这里仅仅只是展示一下标签效果，如果对标签感兴趣，可以查阅文档。
苹果HeaderDoc文档可以参考更多标签，但该文档已经过期，Xcode8中有些已经无效。

四种文档输出工具

HeaderDoc Xcode自带，有详细文档。却只识别/! … /格式，不符合Xcode8快捷注释输出的格式，不是很方便。而且输出的文档零散，没有集合跳转的主页。
Docxygen 支持多语言注释，识别的标签和输出的风格和苹果风格不同，也不是很符合Xcode8快捷注释。
AppleDoc 可以输出与苹果风格相似的文档，也能识别/ … */格式、且能输出文档docset文件。但是Xcode8下好像不管用了，内容不能有效输出。所以也不用这个。
Jazzy 可以输出Swift 和Objective-C文档，且风格几乎和苹果一致，且支持自定义输出主题，能识别快速注释的格式，既有集合跳转的主页也能输出docset文档。所以选这个

Jazzy

官方Git Jazzy

1.安装

sudo gem install jazzy

在命令行执行命令

查看帮助

jazzy-h

输出文档

jazzy \
  --objc \
  --author 小明 \
  --module-version 1.0.0 \
  --umbrella-header DocumentObjC/ViewController.h \
  --framework-root . \
  --module 模块名称   \
  --output docs/objc_output

上面有部分是必须的参数：

--objc
--umbrella-header 汇总的头文件路径，会把该文件引入的其他文件一同输出，所以是必须的（一般框架习惯会有一个汇总的头文件，引入模块涉及到的文件）
--framework-root 框架root路径
--output docs/objc_output 输出的路径

框架路径和头文件路径、输出的路径都是你执行命令的相对路径。

输出效果如下：

文件路径

文档文件:

文档路径

打开index.html:

文档主页

更多命令细节可以查看Git文档
文档所列命令参数有限，也可以查看Git源文件jazzy/lib/jazzy/config.rb查看所有参数

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