はじめに
本稿は 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ライフをお送りください！