Objective-C用のドキュメント作成ツールappledoc

Objective-Cライブラリのドキュメント作成は今までDoxygenを使っていたのですが、もうすこしObjective-C用に適したドキュメント作成ツールがないか調べていたらappledocを見つけました。
その名の通り、Appleの公式リファレンス風のドキュメント生成をしてくれるソフトで、基本的にはdoxygenと似たような使い方をします。試しに使ってみたら結構よい感じでした。

Doxygenとの比較

Apple公式リファレンスに近いフォーマットで出力できるので、ユーザは多分読みやすい。
特にTasksでメソッドを機能ごとに分類できる。
インストールが面倒だったり、GUIアプリがなかったり、慣れていない人(特に技術者以外の人)には使いにくいかも。
まだ若干挙動があやしい部分もある気がする。

もはやドキュメント作成ツールの定番であるDoxygenに比べると、まだ歴史も情報もユーザも少ないので未熟な部分はあります。

インストール

Doxygenに比べるとインストールは若干手間がかかります。おそらく今後はバイナリの形でのダウンロードも可能になると思いますが、現在はソースコードの形で配布されているので、自分でXcodeを使ってビルドする必要があります。

ソースコード類の入手

githubからソースコードをダウンロードする。あるいは、レポジトリをcloneしてもOK。

バイナリのビルド

ダウンロードしたファイルを展開して、その中のappledoc.xcodeprojを開く。
appledocターゲットを選択してビルドする。
ビルドしてできたバイナリを適当な場所に移動する。Xcode4の場合は、~/Library/Developer/Xcode/DerivedData/appledoc~… にビルドされたバイナリが保存されます。
このappledocをホームディレクトリ等、ターミナルから呼び出しやすい位置に移動しておきましょう。

テンプレートと設定ファイルの用意

~/Library/Application Supportにappledocディレクトリを作る。
ダウンロードしたフォルダの中から、Templatesディレクトリの下にあるdocset, htmlディレクトリを~/Library/Application Support/appledocディレクトリの下に移動する。
ここのGlobal settingsに書いてあるplistのサンプルをコピーしてGlobalSettings.plistファイルを作成して、これも~/Library/Application Support/appledocディレクトリに置く。

これでようやくインストール完了です。

ソースコードへのコメント

ドキュメント作成のためのコメントの付け方は、Doxygenとほとんど同じです。クラスやメソッドの定義の直前にコメントを書くとそれがそのクラス／メソッドの説明として処理されます。

/**
 * This is a sample method.
 *
 * @param foo I dunno what this param means.
 */
- (void)someMethodWithFoo:(id)foo;

詳しい説明は本家のドキュメントを参照。

ドキュメント作成

Doxygenと違ってGUIフロントエンド等はないので、コマンドラインからさっきビルドしたバイナリを実行します。
基本的には

appledoc (オプション) [プロジェクトの場所]

という形で実行します。
いくつか指定しないと怒られるオプションがあるので、プロジェクト名や著者名、出力先ディレクトリ等を指定します。

./appledoc --project-name NanteProject --project-company
NanteCompany --create-html --output ./nantedocument
git/nanteproject/

これを実行すると、nantedocumentディレクトリ以下にdocsetやhtmlが生成されます。

感想

生成されるドキュメント自体はObjective-Cに最適化されていて、また普段公式ドキュメントで見慣れているフォーマットだけあってとてもよいし、実際にこれを読んで開発をするデベロッパの方にも喜んでもらえるかなと思います。ただ、インストールが面倒だったり一部挙動があやしい部分があったり(githubには沢山のissue報告が!)するので、今後注意して動向を見ていきたいところです。個人的にはpdf出力がつけばベスト。時間ができたらGUIフロントエンドでも作ろうかな。

リンク

Pocket