リファレンスマニュアルの記述方法を検討し、埋め込み方式のドキュメントツールを採用したとします。Rubyで埋め込み方式のドキュメントツールを使うとしたらRDocかYARDになります¹。

RDocからYARDへの移行方法につなげたいのでYARDを使う方向で話を進めたいわけですが、その前にRDocとYARDの背景や機能の違いを確認しておきましょう。

RDocの背景

RDocはRuby 1.8.1からRuby本体に標準添付されています。Ruby1.8.1は2003年のクリスマスにリリースされているので、もう7年くらい前になります。Ruby本体や標準添付されているライブラリもRDoc用にドキュメントが書かれていますし、Rubyで標準的なドキュメントツールといえばRDocという存在です。

RDocは2004年くらいまではRuby本体のリポジトリ上で活発に開発されていましたが、それから数年は開発が停滞していました。その後、2008年頃より開発リポジトリをRuby本体のリポジトリからRubyForgeのリポジトリに移動して²、再び開発が活発になりはじめます³。RDoc 2.Xがはじまったのもこの頃です。2年後の2010年の12月にRDoc 3.Xがはじまるなど、今でも開発のペースは衰えていません。

と、こう書くとRDocでいいんじゃないかと思うところです。しかし、Ruby 1.9を使っていて日本語も含むドキュメントを扱っていた人はそんなことはないということに気づいているはずです。Ruby 1.9の大きな変更の1つがEncodingの導入ですが、RDoc 2はEncodingの対応が不十分です。RDoc 2でHTMLを生成しようとして、Encoding関連の例外が発生した人もいるのではないでしょうか。

そして、ハマリポイントなのが、Ruby 1.9.2に標準添付されているRDocは RDoc 3ではなくRDoc 2だということです。Encoding関連で問題が発生している人はgemでRDoc 3をインストールして、そっちを試してみてください。

RDocの機能

RDocではドキュメントのマークアップ言語として独自のマークアップ言語を作成しています。MarkdownやTextileなどといったマークアップ言語よりもシンプルで、機能が足りないと感じることが多いかもしれません。特に、Ruby用のドキュメントシステムとして開発されたのにも関わらず、コード用の専用マークアップがないことには驚くかもしれません⁴。

クラスやメソッド用のメタ情報記述方法ではRuby用ドキュメントツールらしい記述がサポートされています。Rubyは動的な言語なので「メソッドを定義するメソッド」⁵も定義できます。そのようなメソッドのドキュメントも記述できるようになっています。

例えば、以下のようにprotected_attr_readerという独自の「メソッドを定義するメソッド」を定義したとします。このとき、protected_attr_readerで定義したメソッドもattr_readerと同じように読み込み専用属性としてドキュメント化して欲しいですよね。RDocでは以下のように記述することによって、独自の「メソッドを定義するメソッド」で定義したメソッドにも適切にドキュメントを記述することができます。

class CoveredBook
  class << self
    def protected_attr_reader(name)
      attr_reader name
      protected name
    end
  end

  ##
  # :attr_reader:
  # タイトルを返す。ただし、内部からのみから利用可能。
  protected_attr_reader :title

  def initialize(title)
    @title = title
  end
end

と、こう書くとRDocでいいんじゃないかと思うところです。しかし、DoxygenやGTK-Docなど他のドキュメントツールにはあるような専用マークアップがありません。例えば、メソッドの引数⁶や戻り値⁷のドキュメントを記述するための専用マークアップがありません。これらはメソッドのドキュメントを読みやすく整形するときに便利です。また、「バージョンいくつから追加された機能」⁸や「非推奨のAPI」⁹を記述する専用マークアップもありません。

現在も開発が継続しており、RDoc 3もリリースされ、継続的に改良されている¹⁰のですが、まだ細かいところのサポートが不足しているという印象です。

YARDの背景

YARDは2007年から開発が始まっています。RDocの開発が再び活発になりはじめたのが2008年頃なので、あまり改良されていなかった当時のRDocに不満を持っていたのかもしれません。

YARDが重視していることは拡張のしやすさです。YARDのトップページにはアピールポイントとして「Preview As You Document」、「Easily Customize Templates」、「Support Your Own DSL」、「Extend, Extend, Extend!」の4つが挙げられています。このうち3つは拡張性に関することです。Rubyは動的な言語なので使われ方も様々です。様々な使われ方をしているときでもドキュメントを記述できるように拡張性を高くしているものと考えられます。

また、RDocとの互換性も重視しています。RDoc用に書かれたドキュメントを変更なしで処理できるため、RDocからの移行も容易です。

YARDの機能

YARDは複数のマークアップ言語をサポートしています。組み込みではRDoc由来のマークアップ言語だけのサポートですが、gemをインストールすることでMarkdownやTextileも利用することができます。チュートリアルや設計に関する文書など、ある程度長めの文書を書くときはRDocのマークアップではなく、より汎用的なマークアップ言語の方を使うのがよいでしょう。

YARDはメソッドなどのメタ情報の記述方法はRDocとは異なる書式を採用しています。YARDはDoxygenやGTK-Docなどと同様に@タグ名という記述方法を採用しています¹¹。YARDではこれをタグと呼んでいます。組み込みで利用できるタグにはRDocにはなかった、引数記述用タグ、戻り値記述用タグ、初出バージョン記述用タグ、非推奨API記述用タグなどライブラリのドキュメントを記述するために必要そうなタグが一通り揃っています。また、タグを追加することもできます¹²。

また、ドキュメントとして抽出したテキスト情報やメタ情報を再利用しやすい形で提供しています。これを利用することでるりまサーチのようなドキュメント検索システムを作りやすくなりそうですが、これについてはまた別の機会にします。

今後はRDocも記述力が高まったりメタ情報の扱いが改良されていくのかもしれませんが、現時点ではYARDの方がより実践的な機能を持っているといえるでしょう。ただし、ドキュメント生成速度はRDoc 3の方が圧倒的に速いです¹³。

まとめ

Ruby用のドキュメントツールであるRDocとYARDについて比較しました¹⁴。YARDの方がよさそうに思えるように書いているので、YARDを使いたくなったかもしれません。次こそはYARDの使い方を紹介できるかもしれません。

ツイートする

フォローする