先日公開した Ruby 用 JSON クラスを RubyForge にスニペットとして登録しました。使い方も書かないで登録しても意味がないので、この機会に今まで興味がありながら手が出せなかった RDoc を使ってみました。これがもう驚くほど簡単で、なんで今まで使わなかったのかー！！と後悔しきりです。そんなわけで、私のように食わず嫌いをしている方に向けて、「30 分で始める RDoc」を目標に（あくまで目標＾＾；）使い始めの手引きを書いてみました。まだ RDoc をご利用でない方、挑戦してみてはいかがでしょうか。

なお、すでに Ruby 一式がインストール済みで、最低限の Ruby の知識があることを前提にしていますので、あらかじめご了承ください。

まず最初に、 RDoc について軽くご紹介しておきます。すでにご存知の方は読み飛ばしてください。 RDoc は Ruby 専用のドキュメント生成ツールで、 Ruby のソースコードからこのような HTML ドキュメントを簡単に生成できます。ソースコードを解析してクラスやメソッドの構成を自動的に反映させるほか、適切なコメントがあれば、それを適切にドキュメントに挿入してくれます。英語版の Ruby ドキュメントや Ruby on Rails のドキュメントなど多数のプロジェクトで利用されているので、目にされたことのある方も多いのではないでしょうか。現在では Ruby 本体に標準で含まれるようになり、名実共に Ruby の標準ドキュメント生成ツールとなっています。

それでは、ともかく使ってみましょう。まずはこちらの記事に掲載したコメントなしの Ruby 用 JSON クラスのソースを適当な場所に "json.rb" という名前で保存し、そのディレクトリで以下のコマンドを実行してください。

rdoc -S -N -c UTF-8 -t "Simple JSON document" -m json.rb json.rb

"doc" というディレクトリが作成され、その中にドキュメントの HTML ファイルなどが自動生成されます。 "doc/index.html" をブラウザに読み込むと、このようなページが表示されるはずです。きちんと JsonParser クラスと JsonBuilder クラスのページが作成され、それぞれに公開メンバがリストアップされていますね。 RDoc をまったく意識していない普通のソースファイルからでも最低限のドキュメントを生成できることがお分かりいただけるかと思います。

微妙に私の趣向も入っていますが、 RDoc を実行するときは、以下のオプションを付ければだいたい問題なくドキュメントが生成できると思います。

rdoc -S -N -c <文字コード> -t <タイトル> -m <デフォルトページ> <対象ファイル>

文字コード

生成する HTML の文字コードを指定します。ソースファイルの文字コードと同じものを指定してください。

タイトル

ページタイトルの文字列を指定します。

デフォルトページ

index.html を表示した際に最初に表示するページを指定します。ファイル名かクラス名を指定すれば OK です。

対象ファイル

ドキュメントを生成する Ruby ソースファイルを指定します。ディレクトリを指定すれば、そのディレクトリ以下のすべての .rb ファイルが対象になります。省略するとカレントディレクトリ以下の .rb ファイルが対象になります。

もしタブの違いでメソッドのソース表示が崩れてしまうときは、 "-w <タブ数>" も加えてみてください。

さて、これだけではあまりに味気ないので、少しコメントを入れてみましょう。 "json.rb" の先頭に以下の内容を加えてみてください。保存するときの文字コードは UTF-8 でお願いします。

# = Simple JSON クラス
#
# JSON 文字列を Ruby オブジェクトに変換する *JsonParser* クラスと
# その逆の変換を行う *JsonBuilder* クラスが含まれています。

そして、先ほどと同じコマンドを実行してください。今度はこのようなドキュメントが生成されたはずです。 "json.rb" のページに上記の内容がスタイル付きで表示されます。このように、 Wiki 的なマークアップでコメントを記述すると、それを自動的に抽出してドキュメントに反映するのです。以下に主なマークアップを挙げておきます。

ドキュメントの生成結果にこだわるあまりソース内のコメントが読みづらくなっては本末転倒ですから、マークアップは最低限にとどめるようにしましょう。

"json.rb" のページの内容を指定する方法はわかりましたが、それでは "JsonParser" のページの内容を指定するにはどうすればいいのでしょうか。これはコメントを書く位置に依存します。各ページの内容は以下の場所にあるコメントから抽出されるのです。

.rb ファイルのページの内容

ファイルの先頭にある、ひと続きのコメント。ただし "#! /usr/bin/ruby" のようなインタープリタ指定行は除く。

クラスのページの内容

クラス定義の直前にある、ひと続きのコメント。

メソッドの説明

メソッド定義の直前にある、ひと続きのコメント。

普段我々がどんな場所にコメントを書くかを考えれば、この方法は非常に合理的ではないでしょうか。

以上を踏まえて、ダミーのクラスを使ったサンプルソースを作ってみました。実際にドキュメントを生成してみれば、どのコメントがどのようにドキュメントに反映されるかがご理解いただけると思います。ドキュメントの生成結果はこちら。

#! /usr/bin/ruby
 
# = RDoc のサンプル
# Author::    歩行者
# Copyright:: Copyright 2007 WebOS Goodies
# License::   ご自由に
#
# このファイルは RDoc[http://rdoc.sourceforge.net/] による
# ドキュメント生成のサンプルです。
#
# そうそう、書き忘れてましたがクラス名は自動的にリンクになります。
# RDocTest, RDocTest#method ってな具合に。
 
# クラスは単なるダミーです。以下、リストの例。
#
# * 通常リスト。
# * 通常リスト。
#
# 1. 番号付きリスト。
# 2. 番号付きリスト。
#    インデントを揃えれば複数行に記述できます。
#    * リストのネストもできます。
 
class RDocTest
 
  # *initialize* メソッドに対するコメントは
  # *new* クラスメソッドのものとして扱われます。
 
  def initialize()
    # 無関係な場所にあるコメントは反映されません。
  end
 
  # [arg1]
  #   定義リストの内容は別の行に記述することもできます。
  # [arg2]
  #   複数行にわたることも
  #   もちろんできます。
  #
  # メソッドの使用例とかを書きたいときは
  #
  #   字下げすれば pre タグで表示されます。
 
  def method(arg1, arg2)
  end
 
  private
 
  # プライベートメソッドは表示されません。
 
  def undocumented()
  end
 
end

以上、本日は Ruby の標準ドキュメンテーションツール RDoc の使い方をご紹介しました。この記事は初めて使う方へのご紹介ということで詳細な部分には触れていませんが、さらなる情報については以下のページが参考になるかと思います。

http://www.kmc.gr.jp/~ohai/rdoc.ja.html
http://pub.cozmixng.org/~the-rwiki/rw-cgi.rb...

ドキュメントをソースの変更に合わせて書き直すのはけっこう面倒な作業ですが、ソース内のコメントがそのまま反映されるならずいぶん楽になりますね。私もこれから書く Ruby のソースには最初から RDoc のコメントを入れるようにしようと思います。うまく活用して、なるべく負担を増やさずにドキュメントを充実させましょう！