BAD_ACCESS

おもにiOS、ときどき変な電子工作、ガジェット話。

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 https://raw.github.com/onevcat/VVDocumenter-Xcode/master/ScreenShot.gif

これは捗りますね。諸岡さんありがとう!

まとめ

リファレンスを整備してappledocの書式になるだけで何故かコードを(見栄え的に)キレイに書こうという気になりますね。ヘッダーファイルにごちゃごちゃ書くのは好かん!という人にはオススメできませんが。今のところいい感じにできております。

広告を非表示にする