Swift國內社區(qū): SwiftMic
簡介
jazzy 是一個命令行工具，用來生成 Swift 或 Objective-C 文檔。
安裝jazzy
使用如下命令進行安裝
[sudo] gem install jazzy
注意：jazzy 依賴于 Xcode command-line developer tools，如果 build 報錯，可嘗試 xcode-select --install 。
提示
作者所用的 macOS 是 10.13.3 ，執(zhí)行
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
}
然后在項目根目錄下執(zhí)行如下命令：
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參數(shù)。
此時，項目根目錄下將會新生成2個目錄（build和docs）。訪問 docs 目錄中的 index.html 將會看到通過 jazzy 生成的文檔。
如何設置Authors
執(zhí)行
jazzy --author CaryZheng即可，--author 后面的名字按實際填寫即可。
生成的文檔主頁
如果項目根目錄下存在 README.md ，Jazzy 會自動將該 README.md 作為文檔主頁來顯示。
效果圖
參考資料
jazzy具體使用指南可參考 官方說明。
