YARD - Ruby向けのコードメタデータとドキュメント生成ツール

作者 Werner Schuster, 翻訳者 金森 諭 投稿日 2008年8月14日 午後6時0分

コミュニティ

Ruby

トピック

IDE,

動的言語

タグ

Merb,

ドキュメンテーション,

IDEs

RubyFringe（Ruby過激派の意味）(リンク)の講演で、Merbプロジェクトの参画者でもあるEngineYardの従業員のYehuda Katz氏(リンク)が未来を見通すためにいくつかのツールを紹介した。それらはドキュメント生成ツールで、そのひとつであるYARD(リンク)ではRubyドキュメントにメタデータを付けることができる。YARDはRDoc形式のデータによく適用するよう設計されているが、異なるマークアップ表記法も扱える。YARDは拡張性が高く、コード生成や別の出力エンジンのための独自ハンドラをプラグインすることができるようになっている。

特徴的なのはコメント内でのメタデータをサポートしていることで、Javadocのようなツールのユーザが慣れ親しんでいる形のメタタグが扱える。次のはYARDのReadme（from the YARD Readme(リンク)）に含まれているコメントだ。

# Reverses the contents of a String or IO object. 
# 
# @param [String, #read] contentsはリバースするデータを格納する 
# @return [String] 辞書順でリバースされたcontents 
def reverse(contents)    
 contents = contents.read if respond_to? :read
 contents.reverse   
end 

このcontentsパラメータについてのコードからメソッドの引数の型についての情報をどのように付加すればいいかがわかる。引数はStringであっても#readメソッドを持つどのようなクラスであってもいいのだ（InfoQは以前プロトコルとダックタイピングに関するアノテーションを付加するいくつかの方法について議論している(参考記事・英語)）。

RDoc 2.1(リンク)とYARDはメソッドについてメタプログラムしてドキュメントを作る機能がある。RDocではコメントを"##"で始めるとメタプログラムの定義となる。特徴的なのは##の後のコメント行を無視してそれに続く要素をメソッド名として扱うことである。

## 
# 何かするメソッド
add_method :foo 

ソースコードに出てこないがクラスインターフェースに含まれているものは以下のようにリンクとして表すことができる。

##
# :method invisible_method 

YARDはプラガブルなハンドラ(リンク)によって構築される。実際に基本機能もハンドラの集まりとして実装されている。新しいハンドラはYARD::Handlers::Baseクラスを拡張することでつくることができ、処理をおこなうクラスをオーバーライドして独自のコード生成を行うハンドラをつくって、内部DSLやRDocに似たことをすることができる。


YARDをプロジェクトで実行すると、収集したコード構造とデータをキャッシュした.yardocデータベースを作る。RDocのriにあたるYRADのyriツールはこのデータベースを使ってドキュメントを対話式に検索することができる。またYARDはデータベースにキャッシュされた情報を使って、解析を何度もおこなわないでも複数の形式でドキュメントを出力することもできる。YARDのキャッシュはIDEによって生成されるコードインデックスに似たもので、より強力なコード検索（たとえば言語要素の検索を単なるフルテキスト検索以上にできる）、コードブラウジングがおこなえたり、プロジェクトの全コードに対してリファクタリングしないといけない時のツールとして使うことできる。

コメント内でメソッドについてのメタデータを扱うというアイディアはRubyの世界では何度も出てきていたことだった。いくつかのプロジェクトではコメントに任意の型アノテーションをもたせる方法を推進している。たとえばMerbには次のようなドキュメント作成ガイドライン(リンク)がある。

 全てのメソッド（publicもprivateも）には明確なメソッドシグネチャが必要です。それには各パラメータの型、各ハッシュで指定可能な値、戻り値の型やその他の情報が含まれます。

Merbは今のところメソッドシグネチャを指定するのに別の表記法を用いている。

SapphireSteelのRuby In Steel IDE(リンク)では型アサーション(リンク)という方法がサポートされている。そのメタデータはJavadocやYARDの@tagとは異なった形式だが、インデックス化されドキュメント作成に使ったりIntelliSense（自動補完などの支援機能）で利用することができる（動画で型アサーションを使ったIntelliSenseの使い方が説明されている(リンク)。

原文はこちらです：http://www.infoq.com/news/2008/07/yard-documentation-generator

• 次へ >