jazzy生成Swift API文档
简介
jazzy 是一个命令行工具，用来生成 Swift 或 Objective-C 文档。
安装jazzy
使用如下命令进行安装
[sudo] gem install jazzy
注意：jazzy 依赖于 Xcode command-line developer tools，如果 build 报错，可尝试 xcode-select --install 。
提示
作者所用的 macOS 是 10.13.3 ，执行
sudo gem install jazzy时提示ERROR: While executing gem ... (Gem::FilePermissionError) You don't have write permissions for the /usr/bin directory.错误，后改成sudo gem install -n /usr/local/bin jazzy即可正常安装。
使用
本篇将以 class、struct 和 enum 为例进行文档注释。
- class
/// MySDK core class
public class MySDK {
/// The name of SDK
public var name = "My Swift SDK"
/// Test method 1
public func testMethod1() {
}
/// Test method 2
///
/// - parameters:
/// - count: test count
public func testMethod2(count: Int) -> String {
return "test"
}
}
- struct
/// Person struct
public struct Person {
/// Person's name
public var name: String
/// Person's age
public var age: Int
}
- enum
/// SDK environment
public enum Environment {
/// Debug enviroment
case debug
/// Release environment
case release
}
然后在项目根目录下执行如下命令：
jazzy
将输出如下类似日志：
$ jazzy
Running xcodebuild
Parsing ViewController.swift (1/3)
Parsing AppDelegate.swift (2/3)
Parsing MySDK.swift (3/3)
100% documentation coverage with 0 undocumented symbols
included 10 public or open symbols
skipped 2 private, fileprivate, or internal symbols (use `--min-acl` to specify a different minimum ACL)
building site
building search index
jam out ♪♫ to your fresh new docs in `docs`
说明
Jazzy 默认只会对
public和open访问权限的声明进行文档化。如果想要包含低级别的访问权限的话，可使用--min-acl命令，后面可携带internal、fileprivate或private参数。
此时，项目根目录下将会新生成2个目录（build和docs）。访问 docs 目录中的 index.html 将会看到通过 jazzy 生成的文档。
如何设置Authors
执行
jazzy --author CaryZheng即可，--author 后面的名字按实际填写即可。
生成的文档主页
如果项目根目录下存在 README.md ，Jazzy 会自动将该 README.md 作为文档主页来显示。
效果图
jazzy_api_doc.png
参考资料
jazzy具体使用指南可参考 官方说明。
