BT

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

| 作者: Werner Schuster フォローする 6 人のフォロワー , 翻訳者 金森 諭 フォローする 0 人のフォロワー 投稿日 2008年8月14日. 推定読書時間: 4 分 |

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

この記事に星をつける

おすすめ度
スタイル

こんにちは

コメントするには InfoQアカウントの登録 または が必要です。InfoQ に登録するとさまざまなことができます。

アカウント登録をしてInfoQをお楽しみください。

あなたの意見をお聞かせください。

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

このスレッドのメッセージについてEmailでリプライする
コミュニティコメント

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

このスレッドのメッセージについてEmailでリプライする

HTML: a,b,br,blockquote,i,li,pre,u,ul,p

このスレッドのメッセージについてEmailでリプライする

ディスカッション

InfoQにログインし新機能を利用する


パスワードを忘れた方はこちらへ

Follow

お気に入りのトピックや著者をフォローする

業界やサイト内で一番重要な見出しを閲覧する

Like

より多いシグナル、より少ないノイズ

お気に入りのトピックと著者を選択して自分のフィードを作る

Notifications

最新情報をすぐ手に入れるようにしよう

通知設定をして、お気に入りコンテンツを見逃さないようにしよう!

BT