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
強調	word
キータイプ	+word+

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

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

参考#

プログラミングRuby 第2版言語編^*1 - 第16章 Rubyのドキュメントを書く
The RWiki - RDoc覚え書き

俗に言うピッケル本 ↩