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 即可正常安装。

    使用

    本篇将以 classstructenum 为例进行文档注释。

    • 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 默认只会对 publicopen 访问权限的声明进行文档化。如果想要包含低级别的访问权限的话,可使用 --min-acl 命令,后面可携带 internalfileprivateprivate参数。

    此时,项目根目录下将会新生成2个目录(builddocs)。访问 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


Log in to reply