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具体使用指南可参考 官方说明。

Demo源码

https://github.com/CaryZheng/JazzyDemo