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

## 「Jazzy」とは？

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

## 環境

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

## セットアップ

### インストール

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

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

$ jazzy -v
jazzy version: 0.9.3
```

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

```bash
$ sudo gem install jazzy
…

$ jazzy -v
bash: jazzy: command not found
```

## 実装

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

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

例

```swift: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ファイルがあるフォルダ)に移動します。

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

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

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

例

```bash
$ 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` で確認できます。

```bash
$ 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` フォルダが作成されます。
<img width="619" alt="スクリーンショット_2018-07-22_12_17_28.jpg" src="https://qiita-image-store.s3.amazonaws.com/0/138245/c93ddd25-a383-73f0-ce9a-a48464cec371.jpeg">


`docs` フォルダにある `index.html` をSafariなどのWebブラウザで開くとドキュメントを閲覧できます。
<img width="524" alt="スクリーンショット_2018-07-22_12_17_59.jpg" src="https://qiita-image-store.s3.amazonaws.com/0/138245/2e9a2af5-a5bb-ec24-e7d6-17c2ee6d2797.jpeg">

<img width="992" alt="スクリーンショット 2018-07-22 11.58.34.png" src="https://qiita-image-store.s3.amazonaws.com/0/138245/c5b8ba74-8a08-2f69-e023-56358ee4560c.png">

おお！Apple公式のドキュメントみたいでオシャレです。

画面左上にドキュメントの作成度がパーセンテージで示されるのが面白いです。
100%を達成したい気持ちになります。

## 不要なファイルの削除

`build` フォルダにはドキュメントの生成時にビルドされた.appファイルなどが格納されています。
不要なので削除できます。

なぜドキュメントを生成するのにビルドするのかはわかりません。
依存関係を確認するのに必要なのでしょうか？

## 注意点

メソッドの引数名が `parameter` だとドキュメント化されずに飛ばされます。
適切な名前に変更するのがいいです。

## おわりに

ここでは簡単にしか紹介していません。
Jazzyの使い方についてもっと詳細に知りたい場合は参考リンクなどをご参照ください。

## 参考リンク

- [realm/jazzy: Soulful docs for Swift & Objective-C](https://github.com/realm/jazzy)
- [[iOS][Swift] 「Jazzy」を使ってSwiftのソースファイルからドキュメントを生成する ｜ Developers.IO](https://dev.classmethod.jp/smartphone/iphone/generate-documentation-using-jazzy/)