先日、UIAlertControllerを便利に使うライブラリALRTを公開しました！
【Swift】UIAlertControllerをもっと便利にするALRTを作りました
ドキュメントもしっかり作ってみようと、Realm製のiOSプロジェクト向けドキュメント自動生成ツール jazzyを試してみたところ、かなりお手軽にそれらしいドキュメントを作ることができました。
コメント入りの自作ライブラリをCocoapodsにPushすると、Cocoadocsというドキュメントページが自動作成されますが、その裏ではjazzyが動いています。
この記事では、Cocoapodsに自作ライブラリを投稿しない人でも、iOSプロジェクトでドキュメントを自動作成できるよう流れを共有します。
完成図
まず、肝心のどんなドキュメントができるかについてですが、以下のようなApple風ドキュメントを作ることができます。
Cocoadocsになりますが、有名ライブラリだと、APIKitやAlamofireのドキュメントページもjazzyで作られています。
手順
1. Xcodeプラグイン Alcatrazをインストール
Xcodeプラグインマネージャー Alcatrazをインストールします。
以下のInstallコマンドをterminalで入力すればOKです。終了したら、Xcodeを再起動してください。
curl -fsSL https://raw.githubusercontent.com/supermarin/Alcatraz/deploy/Scripts/install.sh | sh
2. VVDocumenterをインストール
コメント入力を劇的に楽にしてくれるプラグインVVDocumenterをここでは使います。まずは、Xcode -> Window -> Package Managerで、Alcatrazを起動します。
次に、AlcatrazでVVDocumenterを検索し、インストールします。終わったらXcodeを起動してください。再起動時にプラグインを読み込むか聞かれるので、Load Bundleを選んでください。
3. コメントを入れる
VVDocumenterを使って、コメントを入れていきましょう。
クラス宣言や、メソッドの上で///と入力すると、自動でコメントフォーマットを補完してくれます。
あとは、自分でパラメーターや、返り値の説明や型などを入力していきます。
クラスやメソッドは、publicにしないと、後々ドキュメントに反映されないので注意が必要です。
import UIKit
/// 普通のViewControllerです
public class ViewController: UIViewController {
/**
至って普通のViewDidLoadです
*/
override public func viewDidLoad() {
super.viewDidLoad()
}
/**
2つのIntを足し算します。
- parameter x: Int型の値
- parameter y: Int型の値
- returns: Int
*/
public func addTwoInts(x: Int, y: Int) -> Int {
return x + y
}
}
4. Gemでjazzyをインストール
jazzyをGem経由でインストールします。
一応、Gemをアップデートしておきましょう。
gem update
gem install jazzy
5. jazzyを使ってみる！
Xcodeプロジェクトのルートで、以下のようなjazzyコマンドを入力すると、ドキュメントファイルが生成されます。
jazzy --author 作者名 --author_url 作者URL -o 出力パス
その中のindex.htmlをブラウザなどで開いてみると先ほどのコメントが反映されたドキュメントページができあがっているのがわかります。
番外編：公開
できあがったファイルはGithub Pagesに置くと、ドキュメントサイトとして公開可能です。もちろん自前でホストしても構いません。