「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
実装
ドキュメント化したいメソッドやプロパティにドキュメンテーションコメントを付けます。
メソッドやプロパティの上で ⌥⌘/ を押下すれば自動で挿入されるので、実装してから付けるのがオススメです。
例
/// 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.
…
ここでは省略するので、詳細を見たい方は実際にコマンドを実行してください。
ドキュメントの閲覧
生成に成功すると build と docs フォルダが作成されます。
docs フォルダにある index.html をSafariなどのWebブラウザで開くとドキュメントを閲覧できます。
おお！Apple公式のドキュメントみたいでオシャレです。
画面左上にドキュメントの作成度がパーセンテージで示されるのが面白いです。
100%を達成したい気持ちになります。
不要なファイルの削除
build フォルダにはドキュメントの生成時にビルドされた.appファイルなどが格納されています。
不要なので削除できます。
なぜドキュメントを生成するのにビルドするのかはわかりません。
依存関係を確認するのに必要なのでしょうか？
注意点
メソッドの引数名が parameter だとドキュメント化されずに飛ばされます。
適切な名前に変更するのがいいです。
おわりに
ここでは簡単にしか紹介していません。
Jazzyの使い方についてもっと詳細に知りたい場合は参考リンクなどをご参照ください。