【Swift】jazzyを使ったドキュメントの書き方

この記事ではjazzy.yamlファイルの書き方と、Swiftコード上でのコメントの書き方で使えそうなものをまとめておく。

yamlファイルにコマンドを書いておくと、毎回ターミナル上でコマンドを打つ必要がなく、

「jazzy」

と打つだけでドキュメント生成してくれるので楽。

jazzy.yamlファイルの書き方

# ドキュメント化するスコープ（privateなども使える。以下はpublic以上の公開範囲のものだけドキュメントする場合）
min_acl: public

# 出力先フォルダをクリーンするか否か
clean: true

# 出力先フォルダの指定
output: docs

# 作成者の名前
author: hoge

# 作成者のURL
author_url: https://hogehoge.com

# ドキュメントコメントのないファイルはスキップするか否か
skip_undocumented: true

# ドキュメントにつけるバージョン番号
module_version: 1.0

# コピーライト
copyright: © 2023 - hoge

# ドキュメントのテーマ(apple/fullWidth/jonyの3つから選択可能)
theme: apple

# 指定ファイルはドキュメント対象外（相対パスで指定）
exclude: [SampleApp/Util/Util.swift,
      SampleApp/Common/*
      ]

# ドキュメント実行プロジェクト
xcodebuild_arguments: [ -workspace, SampleApp.xcworkspace, -scheme, SampleApp]

Swiftソースコード上でのコメントの書き方

マークダウンが使えるらしく、見出しなども書くことができる。

注意点として、行頭のスペースや改行などによってうまく出力されないことがあるのでその際はスペースや改行などをいじると正常に出力される。これに関してはよくわからない。

以下実際のサンプル。

/*
ドキュメントコメント開始

## 見出し1

### 見出し2

   ```
print("このプログラムをコードブロックで囲む")
   ```

- リスト1
- リスト2

seealso:でseealsoタイトルをつけられる。
またクラス名などを`（バッククォーテーション）で囲むとドキュメント内のリンクを作成できる。
メソッドを参照する場合引数を書く必要があるが...で省略することができる
   - seealso:
    - `MyClass`
    - `HogeClass.method1(...)` ← 引数省略パターン
    - `HogeClass.method2(hoge:fuga:)` ←引数省略しないパターン

ドキュメント終了
*/
func sampleMethod() {
・・・
}