[[プログラミング言語/Ruby]]

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

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

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


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


**基本的な書き方 [#q1d596cc]
「#」によるコメント行の連続をひとつのかたまり(ブロック)として扱います。

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

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


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

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

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


*** 見出し [#ice9565a]
段落を`='から始めます。
 # = HeadLine-1
 # == HeadLine-2
 # === HeadLine-3
 # ==== HeadLine-4
 # ===== HeadLine-5
 # ====== HeadLine-6


*** リスト [#ge5552ac]
`*'あるいは`-'で始めた行の連続。
 # = Features of Ruby
 # * genuine-object-oriented
 # * made in japan
 # * duck typing
「数字+`.'」で始めると番号付きに、

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

説明リストは、[Term]Descriptionと書く。
 # [Ruby] The genuine-object-oriented,
 #        light-weight, scripting language.


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

以下のインラインは[A-Za-z]の纏まりによる単語(以下word)
に対して使用できます。
| 装飾       | 書式   | 相当するタグ |
| 太字       | *word* | <b>          |
| 強調       | _word_ | <em>         |
| キータイプ | +word+ | <tt>         |
この書式ではなく、相当するタグで囲っても(入れ子にしない限り)
きちんと処理されます。


*** RDoc化の制御 [#h92f3cd6]
ブロック中で行を`--'から始めると、その行から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




* 参考 [#fbbc8c50]
- [[プログラミングRuby 第2版 言語編:http://ssl.ohmsha.co.jp/cgi-bin/menu.cgi?ISBN=4-274-06642-8]]((俗に言うピッケル本)) - 第16章 Rubyのドキュメントを書く
- [[The RWiki - RDoc覚え書き:http://pub.cozmixng.org/~the-rwiki/rw-cgi.rb?cmd=view;name=RDoc%B3%D0%A4%A8%BD%F1%A4%AD]]


トップ   編集 差分 履歴 添付 複製 名前変更 リロード   新規 一覧 検索 最終更新   ヘルプ   最終更新のRSS