More than 5 years have passed since last update.

Swift用ドキュメント生成ツール「Jazzy」のセットアップ&操作方法

Last updated at 2018-11-07Posted at 2018-07-07

「Jazzy」とは？

Swift(+ Objective-C)用のドキュメント自動生成ツールです。
DBで有名な Realm が提供しています。

環境

OS：macOS High Sierra 10.13.1
Xcode：9.2
Swift：4.0.3
Gem：2.7.1
Jazzy：0.9.3

セットアップ

インストール

Gemからインストールします。

$ sudo gem install -n /usr/local/bin jazzy
…

$ jazzy -v
jazzy version: 0.9.3

-n オプションでフォルダを指定しないと正しくインストールされないので注意です。
https://github.com/realm/jazzy/issues/885

$ sudo gem install jazzy
…

$ jazzy -v
bash: jazzy: command not found

実装

ドキュメント化したいメソッドやプロパティにドキュメンテーションコメントを付けます。

メソッドやプロパティの上で ⌥⌘/ を押下すれば自動で挿入されるので、実装してから付けるのがオススメです。

例

HTTPClient.swift

/// HTTPクライアント
class HTTPClient: NSObject {
…
    // MARK: Public Methods

    /// GETメソッドを実行する
    ///
    /// - Parameters:
    ///   - urlString: URL文字列
    ///   - queriesDictionary: クエリディクショナリ
    /// - Returns: レスポンスボディ
    static public func get(urlString: String, queriesDictionary: [String: String]?) -> Any {
        let url = createUrl(urlString: urlString, queriesDictionary: queriesDictionary)
        return runHTTPMethod(requestBody: nil, url: url, method: .get, contentType: .json)
    }
…
}

ドキュメントの生成

まずプロジェクトのルートフォルダ(.xcodeprojファイルがあるフォルダ)に移動します。

$ cd {プロジェクトのルートフォルダ}

移動したら以下のコマンドを実行します。

$ jazzy \
  --clean \
  -- swift-version {Swiftのバージョン} \
  --author {作者名} \
  --author_url {作者のURL} \
  --module {アプリ名}
  --min-acl {アクセス制御レベルの最小}

例

$ jazzy \
  --clean \
  --swift-version 4.0.3 \
  --author "THE Uhooi" \
  --author_url https://theuhooi.com \
  --module RamenViewer \
  --min-acl private

パラメータに空白がある場合はダブルクォーテーション " で括る必要があります。

--min-acl は指定しないと public 以上しかドキュメント化されません。
全てのメソッドやプロパティをドキュメント化したい場合、 private を指定します。
0% documentation coverage with 0 undocumented symbols でドキュメントが全く作成されない場合、このパラメータが指定されていない可能性があります。
https://github.com/realm/jazzy/issues/803

パラメータの詳細は jazzy -h で確認できます。

$ jazzy -h
Usage: jazzy

Options
    -o, --output FOLDER              Folder to output the HTML docs to
    -c, --[no-]clean                 Delete contents of output directory before running.
                                     WARNING: If --output is set to ~/Desktop, this will delete the ~/Desktop directory.
…

ここでは省略するので、詳細を見たい方は実際にコマンドを実行してください。