| Path: | rdoc.ja |
| Modified: | Sat Feb 12 21:38:04 JST 2005 |
このパッケージはRdocとSimpleMarkupというふたつのコンポーネントを含んでいます。 RdocとはRubyのソースファイルに対するドキュメントを生成するアプリケーションです。 JavaDocと同様に、ソースを解析し、クラス、モジュール、メソッドの定義を抜き出して きます(include,requireもです)。そしてこれらの内容とその直前に書かれた コメントを併合し、ドキュメントを出力します(現在はHTMLしか出力できませんが 、この部分は取り替え可能にできています)。Markupとはプレーンテキストを 様々なフォーマットに変換するためのライブラリです。Rdocによってメソッドや クラスに関するドキュメントを生成するとき、コメント部を変換するため に使われます。
インストールすれば、’rdoc’コマンドでドキュメントが生成できます。 (ウインドウズでは’rdoc.bat’です)
% rdoc [options] [names...]
"rdoc —help"と打てば、最新のオプションに関する情報が得られます。
% rdoc
このコマンドでカレントディレクトリ以下にあるすべてのRubyとCのソース からドキュメントを生成します。生成したドキュメントはカレントディレクトリ 直下の’doc’というディレクトリに置かれます。
ドキュメントを読む人に取って便利なように、生成されるドキュメントの インデックスページに中心的なファイに書かれている内容を含めることが できます。例えば、Rdocそのもののドキュメントを生成する場合は、以下の ようにタイプします。
% rdoc --main rdoc/rdoc.rb
RDocが生成するドキュメントのコメント部で使える様々なマークアップの方法は 以下のMarkupの項に書かれています。
RDocは拡張子によってファイルをどう処理すべきかを決めます。ファイル名の 末尾が.rbや.rbwであるファイルはRubyのソースファイル として処理されます。末尾が.cであるファイルはCのソースと して処理されます。それ以外のファイルは単なるSimpleMarkup-styleで記述さ れたファイルとして処理されます(行の先頭に「#」というコメント記号が あってもなくても同じように処理されます)。また、RDocにディレクトリ名が 渡されると、その中のディレクトリを再帰的に走査します。ただしこの場合 RubyとCのソースファイルのみが処理されます。
RDoc is Copyright © 2001-2003 Dave Thomas, The Pragmatic Programmers. It is free software, and may be redistributed under the terms specified in the README file of the Ruby distribution.
RDoc is Copyright © 2001-2003 Dave Thomas, The Pragmatic Programmers. RDocはフリーソフトウェアであり、Rubyの配布物の中のREADMEファイルに書かれている 条件の元で再配布してもかまいません。
RDocはコマンドラインから以下のようにして起動します。
% rdoc <options> [name...]
ファイルをパースし、そこに含まれている情報を集め、出力します。 こうして全ファイルに渡るクロスリファレンスが生成できます。 もし name がディレクトリならば、その中を走査します。 name を指定しなければ、 カレントディレクトリ(とそのサブディレクトリ内)の全てのRubyのファイルを 処理します。
optionsは以下が指定できます。
db_opt :name, :age
それぞれのnameには"=flagtext"というオプションを付けることができます。 例えば、"=rw"とするとattr_accessorと同じように取り扱われます。
れば、そのファイルを上書きせずに、マージするようにします。
コメント部はかなり自然に書くことができます。’#’で始まるコメントも 使えますし、=begin/=endでのコメントも使えます。=begin/=endを使う場合は、 以下のように=beginの行に’rdoc’タグを付ける必要があります。
=begin rdoc Documentation to be processed by RDoc. =end
パラグラフは左のインデントを揃えたテキストのかたまりで構成されます。 それよりも深くインデントされたテキストはそのまま、マークアップを 考慮せずにフォーマットされます。
例えば、上のパラグラフは以下のように書く
1. リストは以下のような記号が付いた
パラグラフである。
* '*' もしくは '-' で普通のリスト
* 数字+ピリオドで番号付きリスト
* アルファベット+ピリオドで
アルファベットリスト
[cat] small domestic animal [+cat+] command to copy standard input
cat:: small domestic animal +cat+:: command to copy standard input
どちらの形式のラベル付きリストでも、ラベルと同じ行から記述部を書き始めた 場合は、その記述部と同じインデントでひとかたまりとなります。 また、ラベルの次の行から記述部を書き始めることもできます。ラベル部の文章が 長くなるならこうしたほうが良いかもしれません。つまり以下の例のどちらでも 良いということです。
<tt>--output</tt> <i>name [, name]</i>::
specify the name of one or more output files. If multiple
files are present, the first is used as the index.
<tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
index areas, or bit ratios of units as
they are processed.
= 見出しレベル1 == 見出しレベル2
以下3、4、…と続きます。
| イタリック体 italic: | _word_ もしくは <em>text</em> |
| ボールド体 bold: | *word* もしくは <b>text</b> |
| タイプライター体 typewriter: | +word+ もしくは <tt>text</tt> |
それぞれ2つ形式がありますが、wordの方は単語を囲うことしかできません。 単語というのは、アルファベットの大文字および小文字とアンダースコアー のみから構成された文字列です(よって日本語では使えません)。また、これらの マークアップ記号の前に「\」という文字を置くと、マークアップが抑制されます。 上の表は以下のようにすれば作れます。
<em>イタリック体</em> _italic_:: \_word_ もしくは \<em>text</em> <b>ボールド体</b> *bold*:: \*word* もしくは \<b>text</b> <tt>タイプライター体</tt> +typewriter+:: \+word+ もしくは \<tt>text</tt>
label[url]の形式でもハイパーリンクが張れます。この場合は lavelが表示され、urlがリンク先となります。label が複数の単語を含んでいる場合(日本語の場合はこっちを使ってください)、
中括弧を使い、<em>{multi word label}[</em>url<em>]</em>としてください。
def fred
...
yield line, address
上のようなメソッド定義に対して、以下の出力が得られます。
fred() { |line, address| ... }
メソッド名の直後に’:yields: …’を含むコメントを書くと、 この出力を上書きできます。
def fred # :yields: index, position
...
yield line, address
上のようにするとお、以下の出力になります。
fred() { |index, position| ... }
module SM #:nodoc:
class Input
end
end
module Markup #:nodoc: all
class Output
end
end
以上のコードでは、SM::Inputのドキュメントのみが出力 されます。
# Extract the age and calculate the
# date-of-birth.
#--
# FIXME: fails if the birthday falls on
# February 29th
#++
# The DOB is returned as a Time object.
def get_dob(person)
...
# ---------------------------------------- # This is the section that I wrote. # See it glisten in the noon-day sun. # ----------------------------------------
markup/simple_markup.rbも見てください。
| Author: | Dave Thomas <dave@pragmaticprogrammer.com> |
| Requires: | Ruby 1.8.1 or later |
| License: | Copyright © 2001-2003 Dave Thomas. Released under the same license as Ruby. |
This software is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose.
このソフトウェアは、商業的適正を保証するほのめかしや ある特定の目的への適合性を含む一切の保証無しに、「あるがまま」で提供する。
この文章は大林一平<ohai@kmc.gr.jp>が翻訳しました。翻訳の内容に疑問がある 場合は、原文を参照してください。また、原文を見てもよくわからない場合は、 RDocを実際に動かしてみるか、ソースコードを見るかしてください。