プログラミング言語/Ruby

RDoc

RDocとは、JavaのJavaDocのような、ソース中のコメントを解析して 生成されるRubyドキュメント形式です。

このドキュメント生成ユーティリティはRuby本体に標準添付され、 コマンドラインからrdocで呼び出せます。

処理できるのは、Rubyスクリプトはもちろん、Ruby用拡張ライブラリの C言語ソースコードも扱えます。 (なぜか、Fortran99にも対応しています :-)

使い方

$ rdoc

で、カレントディレクトリ以下のソースコードをすべて解析して doc/というディレクトリにHTML形式とri形式のドキュメントを生成します。

基本的な書き方

「#」によるコメント行の連続をひとつのかたまり(ブロック)として扱います。

# ファイル先頭のブロック:
# 	ファイルについてのドキュメント
# 

# クラス定義前のブロック:
# 	クラスについてのドキュメント
# 
class SomeClass
  # メソッド定義前のブロック:
  # 	メソッドについてのドキュメント
  # 
  def some_method(arg)
    ...
  end
end

ただ説明を書いておくだけでも有効なドキュメントになるのは 間違いないですが、このブロック中にはSimpleMarkupと呼ばれる 専用のマークアップ文法が使えます。

SimpleMarkup

Wiki文法のような、シンプルな記号と字下げによる マークアップです。

ブロック内で、同じ数だけ字下げされた行の連続が ひとつの段落として扱われ、より字下げしている テキストは整形済みテキストとして扱われます。

# 読みやすさの関係から、
# 段落はこうして、一字下げて書かれることが多いようです。
#   ここはより字下げされているので整形済みとして扱われる
#   require 'hoge/piyo'
#   
#   class Example < Hoge::Piyo
#     ...
#   end

見出し

段落を`='から始めます。

# = HeadLine-1
# == HeadLine-2
# === HeadLine-3
# ==== HeadLine-4
# ===== HeadLine-5
# ====== HeadLine-6

リスト

`*'あるいは`-'で始めた行の連続。

# = Features of Ruby
# * genuine-object-oriented
# * made in japan
# * duck typing

「数字+`.'」で始めると番号付きに、

「アルファベット+`.'」で始めるとアルファベット順リストになる。

説明リストは、[Term]Descriptionと書く。

# [Ruby] The genuine-object-oriented,
#        light-weight, scripting language.

文中要素(インライン)

リンク
クラスやメソッド名には、そのドキュメントへのリンクが張られます。 http:やmailto:、ftp:にURIを続けてもリンクとして解釈されます。 画像ファイルへのリンクはインライン表示に変換されます。

以下のインラインは[A-Za-z]の纏まりによる単語(以下word) に対して使用できます。

装飾書式相当するタグ
太字*word*<b>
強調_word_<em>
キータイプ+word+<tt>

この書式ではなく、相当するタグで囲っても(入れ子にしない限り) きちんと処理されます。

RDoc化の制御

ブロック中で行を`--'から始めると、その行からRDocとしての 取り扱いをしません。それは`++'から行を始めることによって 再開されます。

# Rubyは純オブジェクト指向スクリプト言語です。
# スクリプト言語の手軽さと、オブジェクト指向言語の強力な開発力を
# 兼ね備えます。
#--
# ただ構文木インタプリタだから遅いのが玉に瑕。1.9からはYARVという
# バイトコードインタプリタになって(そこそこに)早くなる。
# というかIOとかのオーバヘッドで処理系の遅さなんて吹き飛んじゃう
# じゃないかよ、どいつもこいつも遅い遅いって…ぶつぶつ。
#++
# さぁ、皆さんもLet's enjoy Ruby!

他には、ドキュメント修飾子を使う方法があります。

ドキュメント修飾子とは、モジュールやクラス、定数や 属性(attr系メソッドの実行)など、RDocの対象になるものの 脇に書いたコメント内で使うものです。

class Hoge
  module Hidden  #:nodoc:
    #このモジュールはRDocにされない
    ...
  end
  
  private
  
  def private_method  #:doc:
    #プライベートメソッドだけど特別RDocにされる
    ...
  end
end

参考


*1 俗に言うピッケル本