いつのまにかもう一年の25分の1が過ぎてしまいました。すっかり更新が途絶えてしまいましたが今年もよろしくお願い致します。
今回の記事は普段からきっちりappledoc等で自分の書いたコードを整理している人にはほとんどお役にたちませんのでご了承いただくか読み飛ばして下さい。
なにをやるのか
去年やろうとしてやれなかったことを今年は地道に片付けていきたいと思います。
まずは、APIリファレンスをなんとかしたいと思います。で何をやるかというと以下の通りです。
- Xcode上でもクイックヘルプできるようにする
- APIリファレンスのドキュメントをちゃんと更新する
- 普段からリファレンスを書くのを意識する
前提
以下のすばらしい記事を見て、先にappledocをインストールしておいてください。
Xcode上でもクイックヘルプできるようにする（Xcode5標準機能）
Xcode5より前のバージョンではappledocの--install-docsetを指定する必要などがありましたが、Xcode5からはappledocの書式にしたがって記述すれば何もしなくてもクイックヘルプとして表示されるようになります。
こんな感じです。(option+クリックで)
APIリファレンスのドキュメントをちゃんと更新する
appledocでプロジェクトをまるっとリファレンス化しようと思ったのですが、何故かコケてしまいました。
（おそらくどこかのファイルに記述しかコードがappledocのパターンにそぐわなかったのかと…）
よくよく考えると全部のクラスファイルをドキュメントする必要も無いかなと思い、公開用のクラスファイルだけをリファレンスのドキュメントを作成するためのディレクトリにコピーするという運用にしました。
アーカイブした後にドキュメントも生成する
この記事が参考になりました。
appledocのドキュメント作成を自動で行うようにする
運用上、リファレンスドキュメントが必要になるクラスを$REFERENCE_DIRに自動的にコピーするようなshellを必要に応じて付け足しています。
YOUR_PROJECT="プロジェクト名"
YOUR_COMPANY="会社名"
REFERENCE_DIR="ドキュメント生成の元になるディレクトリ"
DOCUMENTATION_DIR="ドキュメント生成先のディレクトリ"
#GENERATE_REFERENCE_HTML
if [ -e /usr/local/bin/appledoc ] ; then
/usr/local/bin/appledoc --project-name “$YOUR_PROJECT” --project-company “$YOUR_COMPANY” --create-html --no-create-docset --no-repeat-first-par --output $DOCUMENTATION_DIR $REFERENCE_DIR
fi
これでアーカイブした後に指定したドキュメントのアウトプット先にHTMLで書き出すようになります。
普段からリファレンス書くのを意識する
これが一番大変なんだと思いますが、捗る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
これは捗りますね。諸岡さんありがとう！
まとめ
リファレンスを整備してappledocの書式になるだけで何故かコードを（見栄え的に）キレイに書こうという気になりますね。ヘッダーファイルにごちゃごちゃ書くのは好かん！という人にはオススメできませんが。今のところいい感じにできております。