Xcode5で自分のコードをAPIリファレンス的にまとめていく話

いつのまにかもう一年の25分の1が過ぎてしまいました。すっかり更新が途絶えてしまいましたが今年もよろしくお願い致します。今回の記事は普段からきっちりappledoc等で自分の書いたコードを整理している人にはほとんどお役にたちませんのでご了承いただくか読み飛ばして下さい。

なにをやるのか

去年やろうとしてやれなかったことを今年は地道に片付けていきたいと思います。まずは、APIリファレンスをなんとかしたいと思います。で何をやるかというと以下の通りです。

Xcode上でもクイックヘルプできるようにする
APIリファレンスのドキュメントをちゃんと更新する
普段からリファレンスを書くのを意識する

前提

以下のすばらしい記事を見て、先にappledocをインストールしておいてください。

appledocでドキュメント生成

Xcode上でもクイックヘルプできるようにする（Xcode5標準機能）

Xcode5より前のバージョンではappledocの--install-docsetを指定する必要などがありましたが、Xcode5からはappledocの書式にしたがって記述すれば何もしなくてもクイックヘルプとして表示されるようになります。

Documentation in Xcode 5

こんな感じです。(option+クリックで)

APIリファレンスのドキュメントをちゃんと更新する

appledocでプロジェクトをまるっとリファレンス化しようと思ったのですが、何故かコケてしまいました。（おそらくどこかのファイルに記述しかコードがappledocのパターンにそぐわなかったのかと…）

よくよく考えると全部のクラスファイルをドキュメントする必要も無いかなと思い、公開用のクラスファイルだけをリファレンスのドキュメントを作成するためのディレクトリにコピーするという運用にしました。

アーカイブした後にドキュメントも生成する

この記事が参考になりました。 appledocのドキュメント作成を自動で行うようにする

運用上、リファレンスドキュメントが必要になるクラスを$REFERENCE_DIRに自動的にコピーするようなshellを必要に応じて付け足しています。

これでアーカイブした後に指定したドキュメントのアウトプット先にHTMLで書き出すようになります。

普段からリファレンス書くのを意識する

これが一番大変なんだと思いますが、捗るXcodeのプラグインを教えていただいたのでこれを使ってみなさんもどんどんリファレンスを書きましょう。

onevcat / VVDocumenter-Xcode

プラグインのインストール

git clone git@github.com:onevcat/VVDocumenter-Xcode.git

でクローンしてきたプロジェクトのVVDocumenter-Xcode.xcodeprojを立ち上げて、VVDocumenter-Xcodeにビルドターゲットを設定し、ビルドするだけです。 Xcodeを再起動すると、以下のGifのように///と打つだけでappledocの書式にあわせて、ある程度のところまでリファレンスの記述を補完してくれます。

https://raw.github.com/onevcat/VVDocumenter-Xcode/master/ScreenShot.gif