徒然Ruby（３８）RDoc

今回はRubyプログラムから自動的にドキュメントを作成するRDocについて書きたいと思います。私はこのことについて、エキスパートではありません。この記事も、初心者の体験談だと考えてください。

どのようなプログラムに有効か？

クラスを定義するプログラムに対して有効です。トップレベルのメソッドだけからなるプログラムだとあまり意味がありません。

というのは、RDocはプログラムを解析して、クラスとメソッドを抜き出してドキュメントを作るものだからです。クラスのないプログラム、例えばトップレベルのメソッドだけで作ったプログラムでは、抜き出すものがありません。そのようなプログラムにRDocを適用しても、できあがったドキュメントはとても悲しいものになってしまいます。

RDocの使い方。

Rubyプログラムのあるディレクトリで「rdoc」とコマンドラインに打ち込めば最低限の動作はします。 docディレクトリにHTMLファイルができあがるので、ダブルクリックして見てみましょう。クラスとメソッドが表示されますね。

名前だけでは寂しいですから、ちょっと説明を書き加えましょう。そのためには、そのクラスまたはメソッドの直前にコメントを書きます。例えば次のようなコメントをクラス定義の直前に書き加えます。

=begin rdoc
方程式 ax+by=1 を表すクラス
インスタンスを生成するときにaとbを引数で与える。
solveメソッドで解を得ることができる。
=end

このように、=beginと=endで挟まれた部分はコメントになります。 #を使ったコメントでもOKです。このようなコメントはできあがったHTMLのクラスのところに表示されるようになります。

メソッドについても同様です。

マークアップ

RDoc独自のマークアップがあります。

段落の間は空行で区切る
-または+で始めるとリストを作ることができる
[]で囲んだ文字を項目とし、項目リストを作ることができる。::で項目と説明を区切る方法も可能
1.で順序付きリスト、a.で文字による順序付きリストになる
=、==・・・で見出しになる

その他についてはRubyのドキュメントを参考にしてください。

オプション

オプションはたくさんありますが、良く使われるのはタイトルとメイン画面（ホーム画面）でしょう。

--titleオプションでタイトルを設定。これがブラウザのタブになる（HTMLのtitleタグ相当）
--mainで指定したファイルがホーム画面になる。README.mdなどを指定することが多い

Rakeとの連動

RakefileにRDocでドキュメントを生成するタスクを定義できます。例えば、

require 'rdoc/task'

RDoc::Task.new do |rdoc|
  rdoc.main = "README.md"
  rdoc.title = "Math Programs"
  rdoc.rdoc_dir = "doc"
  rdoc.rdoc_files.include("README.md", "*.rb")
end

これで、

メイン画面がREADME.md
タイトルが「Math Programs」
HTML生成先のディレクトリが「doc」
対象ファイルがREADME.mdとRubyファイル（拡張子がrbのファイル）

となります。 rakeの引数にrdocなどをつけるとタスクが起動されます。

rdoc: RDocでドキュメントを生成
clobber_rdoc: ドキュメントをクリア（削除）＝＞初期状態に戻る
rerdoc: ドキュメントを一から生成。HTMLドキュメントのディレクトリ内は再生成したものだけになる

例

GitHubに「Math-programs」というレポジトリを作りました。そこのdocディレクトリ以下にRDocで生成したドキュメントがあるので、参考にしてください。このタイプのドキュメントはRubyを使っている人は良く見ているはずです。例えばRakeのドキュメントがそうです。

みなさんもライブラリを作ったら、RDocでドキュメントを作ってみましょう。

おもこん

おもこんは「思いつくままにコンピュターの話し」の省略形です