フィードバックはこちら
RDoc は Ruby のドキュメント生成を行うためのライブラリです。rdoc というドキュメント生成のためのコマンドも含んでいます。
このパッケージは RDoc と Markup というふたつのコンポーネントを含んでいます。 RDoc とは Ruby のソースファイルに対するドキュメントを生成するアプリケーションです。 JavaDoc と同様に、ソースを解析し、クラス、モジュール、メソッドの定義を抜き出してきます(include,require もです)。そしてこれらの内容とその直前に書かれたコメントを併合し、ドキュメントを出力します(現在は HTML しか出力できませんが、この部分は取り替え可能にできています)。Markup とはプレーンテキストを様々なフォーマットに変換するためのライブラリです。RDoc によってメソッドやクラスに関するドキュメントを生成するとき、コメント部を変換するために使われます。
インストールすれば、'rdoc' コマンドでドキュメントが生成できます。 (Windows では '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 はコマンドラインから以下のようにして起動します。
$ rdoc <options> [name...]
ファイルをパースし、そこに含まれている情報を集め、出力します。こうして全ファイルに渡るクロスリファレンスが生成できます。 もし name がディレクトリならば、その中を走査します。 name を指定しなければ、カレントディレクトリ(とそのサブディレクトリ内)の全ての Ruby のファイルを処理します。
options は以下が指定できます。
プロテクティッドメソッドやプライベートメソッドも出力に含まれるようになります(デフォルトではパブリックメソッドのみです)。
生成する HTML の charset を指定します。
可能であれば --encoding を使用してください。
ドキュメントが記述されていない要素に関するレポートを出力します。0 以下を指定した場合はレポートを出力しません。0 を指定した場合は、クラス、モジュール、定数、属性、メソッドに関するレポートを出力します。0 以上を指定した場合には、0 を指定した場合に加えて、メソッドの引数に関するレポートを出力します。level を省略した場合は 0 を指定したと見なされます。
ドキュメントが記述されていない要素に関するレポートを出力しません。
実行時に内部情報を出力します。
実行時に内部情報を出力しません。
何もしません。--diagram オプションは廃止されました。
ファイルの出力を行わず、表示だけを行います。
ファイルの出力を行います。
出力ファイルの文字エンコーディングを encoding に指定します。rdoc が読み込んだ全てのファイルはこの文字エンコーディングに変換されます。--charset オプションもありますが --encoding オプションを使用してください。
pattern にマッチするディレクトリおよびファイルを処理の対象から取り除きます。
ファイル名の末尾が .new であるものを、末尾が .old であるものとして取り扱います。例えば '--extension cgi=rb' とすれば、RDoc は ".cgi" で終わるファイルを Ruby のソースとして取り扱います。
--diagram を指定した場合生成された図において、クラスがどのソースファイルで定義されているかを四角で囲うことで示します。複数のファイルで定義されているクラスは複数の四角にまたがった図が作られます。--diagram といっしょに使わなければ意味のないオプションです。(実験的な機能です)
出力済みのファイルの方が新しい場合でも全てのファイルを更新します。 1.9.2 以下では指定しなかった場合は有効になりません。1.9.2 以降は指定しなかった場合でも有効になります。
出力済みのファイルの方が新しい場合のみファイルを更新します。
生成される出力を指定します。
使いかたの概要を表示します。
無効なオプションを指定した場合に、そのオプションを無視して処理を続行します。また、標準エラーに無視されるがオプションが出力されます。標準で有効になっています。
無効なオプションを指定した場合に、標準エラーに情報を出力して終了ステータス 1 でプログラムを終了します。
図のフォーマットを指定します。png、gif、jpeg、jpg が指定できます。指定しなかった場合は png が使われます。--diagram が必要です。
:include: 命令でファイルを探すディレクトリを指定します。 --include を複数使ってもかまいません。これを指定しなくとも処理中のファイルはすべて探索されます。
デフォルトでは、メソッドのソースコードはポップアップウィンドウで表示されます。このオプションを付けると、インラインで表示されます。
ソースコードに行番号を付けます。
最初に表示されるページに置かれるもの(クラス、ファイルなど)を指定します。もし、特定のファイル(例えば、README など)を置きたければ、それをコマンドラインの最初に置くだけでもかまいません。
ri の出力を生成するとき、出力ディレクトリにすでにファイルが存在すれば、そのファイルを上書きせずに、マージするようにします。
すべての出力を一つのファイルに書きだします。
出力先のディレクトリを dir に設定します(デフォルトは "doc" です)。
出力の名前をnameにします(HTML を出力する場合には何の効果もありません)
標準入力を読み込んで HTML に変換し、標準出力に出力します。ファイルへの出力は行わないため、--op などのオプションは無視されます。
クラスやファイルが複数のファイルで定義されていて、ナビゲーションペインのファイルの所をクリックした場合、そのモジュール内のクラスなどは通常はそのファイルで定義されている分しか表示されません。このオプションを指定すると、そのファイルで定義されているかどうかにかかわらず、すべてのモジュール(クラス)内モジュール(クラス)を表示します。
処理進行メッセージを表示しません。
ri で読める出力を生成します。デフォルトでは --ri を指定すると ~/.rdoc に出力されますが、--ri-site で $datadir/ri/<ver>/site に、--ri-system で $datadir/ri/<ver>/system に出力されます。これらすべてはうしろに指定した --op を上書きします。デフォルトのディレクトリは ri のデフォルトのサーチパスです。
コメント内の name というところからインスタンスメソッドへのハイパーリンクを生成します。このオプションを指定しなければ '#' は取り除かれます。
(RDoc のではなく)外部スタイルシートの URL を指定する。
タブの幅を指定する(デフォルトは 8)。
出力生成時に使うテンプレートを指定する(デフォルトは 'html')。実際にはこれで $: の中のディレクトリの rdoc/generators/xxxx_generator が使われる。 (xxxx はフォーマッタによって異なる)。
出力のタイトルを text に指定します。
出力するメソッドの可視性を public、protected、private のいずれかから指定します。指定しなかった場合は protected です。
マークアップのフォーマットを指定します。デフォルトは rdoc です。 markdown、rd、rdoc、tomdoc のいずれかから選択できます。
Root of the source tree documentation will be generated for. Set this when building documentation outside the source directory. Default is the current directory.
Directory where guides, your FAQ or other pages not associated with a class live. Set this when you don't store such files at your project root. NOTE: Do not use the same file name in the page dir and the root of your project
path で指定したファイルかディレクトリを出力先のディレクトリにコピーします。ディレクトリを指定した場合はディレクトリの内容全てをコピーします。このオプションは複数回指定する事ができます。
カレントディレクトリの .rdoc_options ファイルに指定した設定を YAML 形式で保存します。
プログラムの解析時に詳細な情報を表示します。
RDocのバージョンを表示する。
CVS のウェブフロントエンドへのリンクの URL を指定する。URL が '\%s' を含んでいれば、そこがファイル名が置きかえられます。'\%s' を含んでいなければ、ファイル名を指定した URL の後に付けたものを使います。
.rdoc_options ファイルを gem に含める事で、rdoc のオプションを保存する事ができます。また、以下のように --write-options を指定するのが最も簡単です。
rdoc --markup tomdoc --write-options
この場合、自動的に .rdoc_options ファイルが作成されて指定したオプションが保存されます。
ただし、以下のオプションはユーザの指定するオプションや RDoc の通常の動作と干渉するため、保存する事ができません。
コメント部はかなり自然に書くことができます。'#' で始まるコメントも使えますし、=begin/=end でのコメントも使えます。=begin/=end を使う場合は、以下のように =begin の行に 'rdoc' タグを付ける必要があります。
=begin rdoc Documentation to be processed by RDoc. =end
パラグラフは左のインデントを揃えたテキストのかたまりで構成されます。それよりも深くインデントされたテキストはそのまま、マークアップを考慮せずにフォーマットされます。
また、RDocは '#--' を含む行が現われると処理をしなくなります。これで外部向けコメントと内部向けコメントを分離したり、メソッド、クラスモジュールと関係ないコメントを取り除いたりできます。'#++' で始まる行が現われると、処理を再開します。
# 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) ...
リストは以下のような記号が付いたパラグラフです。
例えば、上のパラグラフは以下のように書きます。
リストは以下のような記号が付いた
パラグラフです。
* '*' もしくは '-' で普通のリスト
* 数字+ピリオドで番号付きリスト
* アルファベット+ピリオドで
アルファベットリスト
ラベル付きリスト(description list とも呼ばれる)は通常大括弧でラベルを囲います。
[cat] small domestic animal [+cat+] command to copy standard input
ラベル付きリストはコロン2つをラベルの後に置くことでもマークアップできる。この場合は表形式となり、記述部(コロン2つの後のテキスト)は左揃えになります。この形式は本ドキュメントの末尾のほうの 'author' のところで使われています。
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.
見出し部は ASCII 文字の等号「=」を使います。
= 見出しレベル1 == 見出しレベル2
以下レベル 3、4、…と続きます。
罫線(横方向の線)はASCII文字のハイフン三つ '---' を使います。
文中で以下のようなマークアップもできます。
それぞれ2つ形式がありますが、word の方は単語を囲うことしかできません。単語というのは、アルファベットの大文字および小文字とアンダースコアーのみから構成された文字列です(よって日本語では使えません)。また、これらのマークアップ記号の前に「\」という文字を置くと、マークアップが抑制されます。上の表は以下のようにすれば作れます。
<em>イタリック体</em> _italic_:: \_word_ もしくは \<em>text</em> <b>ボールド体</b> *bold*:: \*word* もしくは \<b>text</b> <tt>タイプライター体</tt> +typewriter+:: \+word+ もしくは \<tt>text</tt>
コメント内のクラス名やソースファイルの名前やメソッド名(アンダースコアーを含んでも良いし「#」が前に付いていても良い)は、自動的にリンクが張られます。
http:、 mailto:、 ftp:、 www. で始まるテキストはウェブへのリンクだと判別されます。外部の画像ファイルを参照している場合は <IMG..> に変換されます。link: で始まる場合はローカルファイルへのリンクであるとみなし、--op で指定したディレクトリからの相対パスとなります。
label[url] の形式でもハイパーリンクが張れます。この場合は label が表示され、url がリンク先となります。label が複数の単語を含んでいる場合(日本語の場合はこっちを使ってください)、
中括弧を使い、<em>{multi word label}[</em>url<em>]</em> としてください。
メソッドのパラメータは抜きだされ、ドキュメントのメソッド記述のところに出力されます。メソッドが yield を呼んでいる場合は、yield に渡されているパラメータもそこに出力されます。
def fred ... yield line, address
上のようなメソッド定義に対して、以下の出力が得られます。
fred() { |line, address| ... }
メソッド名の直後に ':yields: …' を含むコメントを書くと、この出力を上書きできます。
def fred # :yields: index, position ... yield line, address
上のようにすると、以下の出力になります。
fred() { |index, position| ... }
マークアップは <tt> タグ内部などでバックスラッシュ記号でエスケープできます。バックスラッシュ自身を表示する場合は 2 回連続でバックスラッシュを記述します。また、<tt> タグの内側では後ろに続くマークアップ記号 (<tt><*_+</tt>)やバックスラッシュ、リンク記法は削除されます。
例:
\{ruby-lang.org}[www.ruby-lang.org] は以下のように変換されます。
{ruby-lang.org}[www.ruby-lang.org]
\RDoc::RDoc#document は以下のように変換されます。
RDoc::RDoc#document
<tt>\S</tt> は以下のように変換されます。
<tt>S</tt>
これらは RDoc バージョン 1 との互換性を保つために、このような動作になっています。
文章内の文字列は以下のように置換されます。
コメント部には他にも以下の命令を含めることができます。
':yield:' はドキュメント修飾子の一例です。以下の修飾子は修飾しようとしている部分の直後に書きます。ほかにも以下のようなものがあります。
指定した要素をドキュメントに含めません。クラスやモジュールを指定した場合、それに直接含まれるメソッドやエイリアスや定数や属性も省略されます。しかし、デフォルトでは、指定したモジュールやクラスに含まれるモジュールやクラスはドキュメントに 含まれます。これをオフにしたい場合は all 修飾子を加えます。
module SM #:nodoc:
class Input
end
end
module Markup #:nodoc: all
class Output
end
end
以上のコードでは、SM::Input のドキュメントのみが出力されます。
ドキュメント要素(クラス、メソッドなど)をドキュメントに含めるかどうかを制御します。例えば、あるクラスにドキュメントに出力したくない定数があるとすると、その前に :stopdoc: を置き、後ろに :startdoc: を置きましょう。もし :startdoc: を置かなければ、そのクラス、モジュール全体がドキュメントに出力されなくなり ます。
指定したメソッドや属性を強制的にドキュメントに含めます。これは例えば特定のプライベートメソッドをドキュメントに含めたい場合に便利です。
以降の内容を一切ドキュメントに出力しません。
これはインスタンスメソッドの initialize にのみ適用できます。通常、 RDoc は initialize メソッドのドキュメントやパラメータを実際にはクラスメソッド new のものと仮定し、initialize の代わりに new を出力します。:notnew: 修飾子はこれを止めさせます。initialize メソッドは protected なので、コマンドラインで -a を指定するなどしない限り、 initialize メソッドに関するドキュメントは出力されないことに注意してください。
指定した場所に指定したファイルを挿入します。ファイルを探すディレクトリは --include で指定したものとカレントディレクトリです。挿入されるファイルは :include: 命令を置いたのと同じだけインデントされます。
ドキュメントのタイトルを指定します。コマンドラインの --title パラメータと同じ働きをします。(コマンドラインでの指定のほうが優先されます)
コマンドラインの --main パラメータと同じ働きをします。
新しいセクションを開始します。:section: の後ろに置いたタイトルはそのセクションの見出しとなります。そして、コメントの残りの部分はそのセクションの導入文となります。その後ろのメソッド、エイリアス、属性、クラスはこのセクションに含まれます。:section: 命令の前に何行かあってもかまいません。それらはドキュメントには含まれず、またそれとまったく同じ内容の行がブロックの終端にあった場合、それも取り除かれます。そのため、以下のような装飾をすることが できます。
# ----------------------------------------
# :section: My Section
# This is the section that I wrote.
# See it glisten in the noon-day sun.
# ----------------------------------------
記述した要素の :section: を title で指定したものに上書きします。
# :category: Utility Methods
#
# CGI escapes +text+
def convert_string text
CGI.escapeHTML text
end
title を省略した場合は、:section: を指定しなかった場合と同じように扱われます。
# :category:
#
# This method is in the default category
def some_method
# ...
end
:section: とは異なり、以降のドキュメントには影響しません。直後の要素のみに影響します。
デフォルトではメソッドの引数や yield の引数をパースして出力しますが、これを指定した次の行から次の空行までをメソッド呼び出し列と解釈し、出力をそこに書かれたように変更します。
現在のマークアップの指定を type で指定したフォーマットで上書きします。ファイルの先頭で :markup: を記述した場合、ファイル全体に適用されます。
# coding: UTF-8
# :markup: tomdoc
# tomdoc 形式のコメントを記述 ...
class MyClass
# ...
それ以外では適用が限定されます(以下の例では some_method のみ):
# ...
end
# :markup: rdoc
#
# rdoc 形式のコメントを記述 ...
def some_method
# ...
ただし、異なるマークアップのフォーマット同士を変換するのでもない限り、.rdoc_options ファイルでマークアップのフォーマットを指定してプロジェクト全体を設定してください (rdoc/オプションの保存 参照)。
マークアップの形式を追加したい場合は http://docs.seattlerb.org/rdoc/DEVELOPERS_rdoc.html を参照してください。
また、他にも Ruby スクリプト、Ruby から使用するために書かれた C 言語のソースコードのみで指定できる命令があります。それらについては rdoc/parser/ruby、rdoc/parser/c を参照してください。
| RDoc | rdoc ドキュメントを扱うためのモジュールです。 |
| RDoc::Error | ドキュメントの処理中にエラーがあった場合に発生します。 |
| rdoc/alias | RDoc::Alias を定義するサブライブラリです。 |
| rdoc/anon_class | RDoc::AnonClass を定義するサブライブラリです。 |
| rdoc/any_method | RDoc::AnyMethod を定義するサブライブラリです。 |
| rdoc/attr | RDoc::Attr を定義するサブライブラリです。 |
| rdoc/class_module | RDoc::ClassModule を定義するサブライブラリです。 |
| rdoc/code_object | RDoc::CodeObject を定義するサブライブラリです。 |
| rdoc/code_objects | Ruby のソースコード中にあるクラス、モジュール、メソッドなどの構成要素を表現するためのサブライブラリです。 |
| rdoc/constant | RDoc::Constant を定義するサブライブラリです。 |
| rdoc/context | RDoc::Context と RDoc::Context::Section を定義するサブライブラリです。 |
| rdoc/generator | RDoc が解析したソースコードを RDoc::CodeObject のツリーからその他の形式に出力するためのサブライブラリです。 |
| rdoc/generator/darkfish | HTML を生成するためのサブライブラリです。 |
| rdoc/generator/json_index | 他のジェネレータが生成する HTML で検索が行えるように、JSON の検索インデックスを生成するサブライブラリです。 |
| rdoc/generator/markup | ライブラリ内部で使用します。 |
| rdoc/generator/ri | ri のためのファイルを生成するためのサブライブラリです。 |
| rdoc/ghost_method | RDoc::GhostMethod を定義するサブライブラリです。 |
| rdoc/include | RDoc::Include を定義するサブライブラリです。 |
| rdoc/known_classes | Ruby の組み込みクラスに関する定数を定義するサブライブラリです。 |
| rdoc/markdown | Markdown 形式で記述されたドキュメントを rdoc 上で解析するためのサブライブラリです。 |
| rdoc/markdown/entities | HTML の実体参照のマッピングを表す情報を定義するサブライブラリです。 |
| rdoc/markup | RDoc 形式に整形されたプレインテキストを変換するためのサブライブラリです。 |
| rdoc/markup/formatter | RDoc 形式のドキュメントを整形するためのサブライブラリです。 |
| rdoc/markup/to_ansi | RDoc 形式のドキュメントを ANSI エスケープシーケンスで色付けするサブライブラリです。 |
| rdoc/markup/to_bs | RDoc 形式のドキュメントをエスケープシーケンスで太字やアンダーラインの効果を持たせるように見せるサブライブラリです。 |
| rdoc/markup/to_html | RDoc 形式のドキュメントを HTML に整形するためのサブライブラリです。 |
| rdoc/markup/to_html_crossref | RDoc 形式のドキュメントを HTML に整形するためのサブライブラリです。 |
| rdoc/markup/to_rdoc | RDoc 形式のドキュメントをマークアップ記法を保持したまま出力させるためのサブライブラリです。 |
| rdoc/meta_method | RDoc::MetaMethod を定義するサブライブラリです。 |
| rdoc/normal_class | RDoc::NormalClass を定義するサブライブラリです。 |
| rdoc/normal_module | RDoc::NormalModule を定義するサブライブラリです。 |
| rdoc/options | rdoc コマンドのオプションを解析するためのサブライブラリです。 |
| rdoc/parser | rdoc で解析できるファイルの種類を追加するためのサブライブラリです。 |
| rdoc/parser/c | C 言語で記述されたソースコードから組み込みクラス/モジュールのドキュメントを解析するためのサブライブラリです。 |
| rdoc/parser/changelog | ChangeLog ファイルを解析するためのサブライブラリです。 |
| rdoc/parser/markdown | Markdown 形式で記述されたファイルを解析するためのサブライブラリです。 |
| rdoc/parser/rd | RD 形式で記述されたファイルを解析するためのサブライブラリです。 |
| rdoc/parser/ruby | Ruby のソースコードを解析するためのサブライブラリです。 |
| rdoc/parser/ruby_tools | RDoc::RubyLex と RDoc::RubyToken を使って Ruby のソースコードのパーサを記述するためのモジュールを定義するサブライブラリです。 |
| rdoc/parser/simple | ソースコード以外のファイルを解析するためのサブライブラリです。 |
| rdoc/parser/text | プログラムを含まないテキストを解析するためのサブライブラリです。 |
| rdoc/rdoc | rdoc コマンドのためのサブライブラリです。 |
| rdoc/require | RDoc::Require を定義するサブライブラリです。 |
| rdoc/ruby_token | (uninitialized) |
| rdoc/single_class | RDoc::SingleClass を定義するサブライブラリです。 |
| rdoc/stats | RDoc のステータスを管理するサブライブラリです。 |
| rdoc/text | コメントテキストを処理するためのサブライブラリです。 |
| rdoc/token_stream | トークンを管理するためのサブライブラリです。 |
| rdoc/top_level | RDoc::TopLevel を定義するサブライブラリです。 |
フィードバックはこちら