見やすいリファレンス生成。Ruby製のドキュメントシステム「YARD」
YARDはRubyのコードからドキュメントを生成するライブラリです。
システム開発をしていて一定以上の規模になるとどうしてもドキュメントが欲しくなってきます。それは最低限必要なドキュメントの一つです。今回はコード中に書き込んだコメントからドキュメントを生成してくれるYARDを紹介します。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.13.38.1366598811.png)
インストールしました。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.15.02.1366598814.png)
yardocコマンドでドキュメントを生成します。docディレクトリの中に生成されます。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.16.04.1366598817.png)
コントローラやモデルが一覧されています。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.16.13.1366598821.png)
メソッドやサブクラスなどが表示されています。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.17.12.1366598824.png)
サーバとして立てることもできます。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.17.22.1366598833.png)
クラスリストはメニューから。
[](http://images.moongift.jp/2013/04/Screenshot 2013-04-22 9.17.34.1366598838.png)
メソッドのリストも取れます。
YARDは次世代のrDocとして期待されているドキュメントシステムになります。@〜という形でパラメータや返り値、サンプルコードなどを記述します。サーバとして立ち上げて、プレビューしながら書いていけばドキュメント作成がさくさく進むのではないでしょうか。
YARDはRuby製、MIT Licenseのオープンソース・ソフトウェアです。
MOONGIFTはこう見る
システム開発において、ムダなドキュメントを作成する必要はありませんがドキュメント全体が無用という訳ではありません。特にこの手のメソッドの説明などを記述した文書は、システムの処理を知る上でも大事なドキュメントになるでしょう。コードを見れば分かる、は相当投げやりです。
そのような運用をしているとメソッドの書き換えすら難しくなります。期待されている処理が明文化されていれば、そのメソッドを利用して処理を行うのも難しくありません。また文書化が難しいメソッドであればリファクタリングする等といったルールも適用しやすくなるでしょう。