Road To RDoc
(この記事はRuby Advent Calendar jp: 2009の8日目の記事です.前の方はすがまさおさんで,後の方は@Sixeightさんです.)
YARD
プログラミング言語では,コメントから自動的にドキュメントを生成するツールが大抵用意されていて,RubyにもRDやRDocがあります.RDocは広く使われているので,Rubyistであれば使ったことがあるんじゃないかと思います.そんな中でDataMapperやHamlなど,最近使われるようになってきているのがYARDです.gemが用意されているので
$ gem install yard
でyardocやyriなどが使えるようになります.
yardoc
RDocみたいなもので,ソースからドキュメントを生成してくれます.書式は以下のような感じです(スタートガイドから引用).
# Converts the object into textual markup given a specific format. # # @param [Symbol] format the format type, `:text` or `:html` # @return [String] the object converted into the expected format. def to_format(format = :html) # format the object end
@tagというスタイルで,Javadocなどを使ったことがある方にはしっくり来るのではないかと思います.生成されたドキュメントはこんな感じになります.
他に使えるタグなどはドキュメントを参照して下さい.
yri
riのYARD版です.YARDではyardocでドキュメントを生成すると,同時にデータベースも構築します(.yardocという名前で保存される).yriではそれを使ってriのようにクラスやメソッドなどを表示出来ます.
今後
最新版が0.4で1.0にはまだまだ遠いYARDですが,テンプレート機能やクエリ機能など現状でも使えるツールだとは思うで,「RDやRDocはなんか合わないなぁ」と思われている方は使ってみてはどうでしょうか!!
実はロードマップもちゃんと存在していて,1.0になると…
余談
最初は「Webアプリケーションの本質を知る」という記事にするつもりだったのですが,Tipsじゃないやということで今回の内容に変更したのでした.