iOSアプリやSDKのドキュメントをコマンド一発でいい感じに作る

はじめに

Xcodeを使ってアプリやSDKを作る仕事をしていると「インターフェースのドキュメント作って。明日までね」なんて言われることがあります（怒）
そんなときのために、コマンド1個でいい感じのドキュメントを生成する方法をここに残しておきます。

必要なもの

• Xcode
• 対象プロジェクト
• jazzy（後述）

手順

1. jazzyのインストール

ターミナルを開いて以下を実行します。

> sudo gem install jazzy

Successfully installed jazzy-0.15.1
となれば成功です。

jazzyはSwiftとObjective-C用のソウルフルなドキュメント生成ツールらしいです。

2. 設定ファイルを作成

プロジェクト直下に.jazzy.yamlという名前で作成し、以下をコピペします。
（設定値は自分のプロジェクトに合わせて適宜変更してください）

.jazzy.yaml

# public以上がドキュメント化される。より低いアクセスレベルも指定できる。
# [private | fileprivate | internal | public | open]
min_acl: public

#実行前に出力先フォルダをクリーン
clean: true

# ドキュメント出力先フォルダ
output: document

# 著者
author: 著者

# コピーライト
copyright: '&copy; 2024 <a class="link" href="" target="_blank" rel="external noopener">コピーライト</a>. All rights reserved.'

# xcodebuildの引数
xcodebuild_arguments: [archive,-scheme,【プロジェクトのScheme】,-configuration,Debug,-destination=iOS,-arch,arm64,-sdk,iphoneos,SKIP_INSTALL=NO,BUILD_LIBRARY_FOR_DISTRIBUTION=YES]

3. ドキュメント生成

ターミナルで以下のコマンドを実行します。

> jazzy

outputに指定したフォルダへドキュメントが生成されます。
手順としてはこれで終了です。簡単ですね。

成果物

サンプルプロジェクト

どんなものができるのか、例として以下のようなプロジェクトを作って試してみます。

ViewController.swift

import UIKit

public class ViewController: UIViewController {
    /// **viewDidLoad**
    public override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
    }

    /// **XX処理**
    ///
    /// XXの処理を行います。
    public func test1()  {
    }
    
    /// **XX判定**
    ///
    /// XXの判定を行います。
    ///
    /// - note:
    ///     - 〇〇だった場合、true
    ///     - △だった場合、false
    /// - Parameters:
    ///   - val: 引数
    /// - Since: 1.0.0
    /// - SeeAlso: SDK初期化要求 ``test1()``
    /// - SeeAlso: 合否結果``Constants.Result``
    ///
    public func test2(val: Int) -> Bool {
        return true
    }
}

public class Constants {
    public enum Result {
        /// 正常終了
        case success
        /// 異常終了
        case failure
    }
}

できたもの

いい感じのドキュメントが出来上がりましたね。
READMEをプロジェクトに設置しておけば、ドキュメントにも反映してくれます。

さいごに

楽ちんですね。
.jazzy.yamlをgit等でチームメンバーと共有すれば、誰でも作る事ができます。
READMEに更新履歴を残しておくような運用にすれば社外に出しても恥ずかしくないドキュメントになるのではないでしょうか。