jazzyでSwiftのコードから簡単なリファレンスを生成する。 #Swift

はじめに

本稿は Swift その2 Advent Calendar 2017 の14日目の投稿です。

当方Swiftをがっつりとできるわけではないですが、頑張りたいと思いますのでよろしくお願いします！

やりたいこと

みなさんは自分が作成したライブラリとかソースとかに対して、リファレンス書いてますか？
僕は書いてないです。作るのは結構面倒なんですよね...
PHPならDoxygenとかあるので、Swiftは対応してないみたいだし...と思ってたらありました！
Realmが提供してくれているjazzyです！ぱっと見た感じ見た目も綺麗だし、割と簡単に導入ができるみたいなので、試してみましょう！

jazzyの簡単な説明

SwiftのDocコメントを利用して、プロジェクトのリファレンスをHTMLで吐き出してくれるツールです！
詳しくはGitHubにリポジトリがあるので、そちらを参照してください。

やっていこう

※Swiftなのでもちろんmacが前提です。

jazzyのインストール

gemが入っていれば簡単にインストールできます。
なんとこれだけ！

$ gem install jazzy

ソースコードの準備

試しにソースコードを作成します。
コメントの書き方がPHPっぽいですが、好みの問題なので自分なりに書きましょう！

import UIKit

/**
 * サンプル提示用ののコントローラー
 *
 * - Author: Satoshi Baba (s_baba@currentia.co.jp)
 * - Date: 2017/09/01
 * - Copyright: © 2017年 Currentia Inc. All rights reserved.
 */
class SampleViewController: UIViewController {

    //------------------------------
    // MARK: メンバー変数
    //------------------------------

    /// 文字列を格納する。
    var sampleParam1:String = ""

    //------------------------------
    // MARK: 関数
    //------------------------------
    /**
     * ViewControllerの生成時に呼び出される。
     */
    override func viewDidLoad() {
        super.viewDidLoad()
    }

    /**
     * サンプルメソッド
     * 説明の後は必ず1行空けること
     *
     * - parameter value1: 変数１
     * - parameter value2: 変数２
     * - returns: value1とvalue2の連結文字列
     * - throws: エラー時にNSErrorをthrowする。
     */
    func sampleMethod(_ value1: String?, value2: String?) throws -> String {
        if (value1 == nil || value2 == nil) {
            throw NSError()
        }
        return value1! + value2!;
    }


}

実行してみる

jazzyを実行してみましょう。
XCodeのプロジェクトに移動して、以下のコマンドを打つだけで生成されます。

$ jazzy -o output/ --min-acl internal

outputというディレクトリができているはずなので、index.htmlとか開くといい感じに出力されているのが確認できますね！

(COntrollerになっているのは、見ないフリでお願いします。)

まとめ

これで簡単にリファレンスが吐き出せるようになりました。
後からDocコメントを整備するのはしんどいので、ぜひ初期の段階で書式ルールに乗っ取って書きたいですね！
皆様より良いSwiftライフをお送りください！