= RDOC - Ruby Documentation System このパッケージはRdocとSimpleMarkupというふたつのコンポーネントを含んでいます。 RdocとはRubyのソースファイルに対するドキュメントを生成するアプリケーションです。 JavaDocと同様に、ソースを解析し、クラス、モジュール、メソッドの定義を抜き出して きます(include,requireもです)。そしてこれらの内容とその直前に書かれた コメントを併合し、ドキュメントを出力します(現在はHTMLしか出力できませんが 、この部分は取り替え可能にできています)。Markupとはプレーンテキストを 様々なフォーマットに変換するためのライブラリです。Rdocによってメソッドや クラスに関するドキュメントを生成するとき、コメント部を変換するため に使われます。 == ロードマップ * RdocでRubyのソースファイルに対するドキュメントを生成したければ、 まずこの文章を読みましょう。 * Cで書かれた拡張ライブラリを含めたければ、 rdoc/parsers/parse_c.rbを見てください。 * コメント部で使えるマークアップについて知りたければ、markup/simple_markup.rb を見てください。 * RDocをライブラリとして使いたければ、RDoc::RDocを見てください。 * テキスト部をHTMLに変換する部分をライブラリとして使いたければ、 SM::SimpleMarkupを見てください。 * 独自のHTMLテンプレートで出力したければ、RDoc::Pageを見てください。 == 概要 インストールすれば、'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/parse.rb内のRubyのパーザは日本ラショナルの石塚圭樹氏の傑出した 成果を元にしている。彼はirbとrtags用にRubyのパーザを書きました。 * クラスやモジュールを図にするコードはEnticlaのSergey A Yanovitsky (Jah)氏 によって書かれました。 * Charsetに関するパッチはMoonWolf氏によるものです。 * kilmer.rbはRich Kilmer氏によります。 * RDFフォーマットはDan Brickleyが中心となって設計しました。 == ライセンス RDoc is Copyright (c) 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 (c) 2001-2003 Dave Thomas, The Pragmatic Programmers. RDocはフリーソフトウェアであり、Rubyの配布物の中のREADMEファイルに書かれている 条件の元で再配布してもかまいません。 ---- = 使いかた RDocはコマンドラインから以下のようにして起動します。 % rdoc [name...] ファイルをパースし、そこに含まれている情報を集め、出力します。 こうして全ファイルに渡るクロスリファレンスが生成できます。 もし name がディレクトリならば、その中を走査します。 name を指定しなければ、 カレントディレクトリ(とそのサブディレクトリ内)の全てのRubyのファイルを 処理します。 optionsは以下が指定できます。 [--accessor name[,name...]] nameで指定したメソッドをattr_xxxと同様なものとして 取り扱います。例えば"--accessor db_opt"とすると、以下のような行も RDocによって処理されドキュメントに含まれるようになります。 db_opt :name, :age それぞれのnameには"=flagtext"というオプションを付けることができます。 例えば、"=rw"とするとattr_accessorと同じように取り扱われます。 [--all] プロテクティッドメソッドやプライベートメソッドも出力に含まれるよう になります(デフォルトではパブリックメソッドのみです)。 [--charset _charset_] 生成するHTMLのcharsetを指定します。 [--diagram] モジュールやクラスを表示するのに図を使うようになります。この機能は 実験的なもので、すべての出力テンプレートに対応しているわけでは ありません。dot V1.8.6かそれ以降がなければ"--diagram"オプションは 正しい出力ができません(http://www.research.att.com/sw/tools/graphviz/)。 [--exclude pattern] patternにマッチするディレクトリおよびファイルを処理の対象から 取り除きます。 [--extension new=old] ファイル名の末尾が.newであるものを、末尾が.oldであるもの として取り扱います。例えば'--extension cgi=rb'とすれば、RDocは".cgi" で終わるファイルをRubyのソースとして取り扱います。 [--fileboxes] --diagramを指定した場合生成された図において、クラスがどのソースファイルで 定義されているかを四角で囲うことで示します。複数のファイルで定義されている クラスは複数の四角にまたがった図が作られます。--diagramといっしょに 使わなければ意味のないオプションです。(実験的な機能です) [--fmt _fmt_] 生成される出力を指定します。 [--help] 使いかたの概要を表示します。 [--help-output] 出力に関するオプションを解説します。 [--image-format gif/png/jpg/jpeg] 図のフォーマットを指定します。png、gif、jpeg、jpgが指定できます。 指定しなかった場合はpngが使われます。--diagramが必要です。 [--include dir,...] :+include+:命令でファイルを探すディレクトリを指定します。 --includeを複数使ってもかまいません。これを指定しなくとも 処理中のファイルはすべて探索されます。 [--inline-source] デフォルトでは、メソッドのソースコードはポップアップウィンドウで 表示されます。このオプションを付けると、インラインで表示されます。 [line-numbers] ソースコードに行番号を付けます。 [--main _name_] 最初に表示されるページに置かれるもの(クラス、ファイルなど)を指定します。 もし、特定のファイル(例えば、READMEなど)を置きたければ、それをコマンド ラインの最初に置くだけでもかまいません。 [--merge] _ri_の出力を生成するとき、出力ディレクトリにすでにファイルが存在す れば、そのファイルを上書きせずに、マージするようにします。 [--one-file] すべての出力を一つのファイルに書きだします。 [--op _dir_] 出力先のディレクトリを_dir_に設定します(デフォルトは"doc"です)。 [--opname _name_] 出力の名前をnameにします(HTMLを出力する場合には何の効果もありません) [--promiscuous] クラスやファイルが複数のファイルで定義されていて、ナビゲーション ペインのファイルの所をクリックした場合、そのモジュール内のクラスなどは 通常はそのファイルで定義されている分しか表示されません。このオプション を指定すると、そのファイルで定義されているかどうかにかかわらず、 すべてのモジュール(クラス)内モジュール(クラス)を表示します。 [--quiet] 処理進行メッセージを表示しません。 [--ri, --ri-site, _and_ --ri-system] _ri_ で読める出力を生成します。デフォルトでは--riを指定すると~/.rdoc に出力されますが、--ri-siteで$datadir/ri//siteに、--ri-systemで $datadir/ri//systemに出力されます。これれすべてはうしろに指定した --opを上書きします。デフォルトのディレクトリはriのデフォルトのサーチ パスです。 [--show-hash] コメント内の#nameというところからインスタンスメソッドへのハイパーリンク を生成します。このオプションを指定しなければ'#'は取り除かれます。 [--style stylesheet url] (RDocのではなく)外部スタイルシートのURLを指定する [tab-width _n_] タブの幅を指定する(デフォルトは8)。 [--template name] 出力生成時に使うテンプレートを指定する(デフォルトは'standard')。 実際にはこれで$:の中のディレクトリのrdoc/generators/xxxx_templateが使われる。 (xxxxはフォーマッタによって異なる)。 [--version] RDocのバージョンを表示する [--webcvs _url_] CVSのウェブフロントエンドへのリンクのURLを指定する。URLが'\%s'を含んで いれば、そこがファイル名が置きかえられます。'\%s'を含んでいなければ、 ファイル名を指定したURLの後に付けたものを使います。 = Markup コメント部はかなり自然に書くことができます。'#'で始まるコメントも 使えますし、=begin/=endでのコメントも使えます。=begin/=endを使う場合は、 以下のように=beginの行に'rdoc'タグを付ける必要があります。 =begin rdoc Documentation to be processed by RDoc. =end パラグラフは左のインデントを揃えたテキストのかたまりで構成されます。 それよりも深くインデントされたテキストはそのまま、マークアップを 考慮せずにフォーマットされます。 1. リストは以下のような記号が付いたパラグラフである。 * '*' もしくは '-' で普通のリスト * 数字+ピリオドで番号付きリスト * アルファベット+ピリオドでアルファベットリスト 例えば、上のパラグラフは以下のように書く 1. リストは以下のような記号が付いた パラグラフである。 * '*' もしくは '-' で普通のリスト * 数字+ピリオドで番号付きリスト * アルファベット+ピリオドで アルファベットリスト 2. ラベル付きリスト(description listとも呼ばれる)は通常大括弧でラベルを囲う。 [cat] small domestic animal [+cat+] command to copy standard input 3. ラベル付きリストはコロン2つをラベルの後に置くことでもマークアップできる。 この場合は表形式となり、記述部(コロン2つの後のテキスト)は左揃えになります。 この形式は本ドキュメントの末尾のほうの'author'のところで使われています。 cat:: small domestic animal +cat+:: command to copy standard input どちらの形式のラベル付きリストでも、ラベルと同じ行から記述部を書き始めた 場合は、その記述部と同じインデントでひとかたまりとなります。 また、ラベルの次の行から記述部を書き始めることもできます。ラベル部の文章が 長くなるならこうしたほうが良いかもしれません。つまり以下の例のどちらでも 良いということです。 --output name [, name]:: specify the name of one or more output files. If multiple files are present, the first is used as the index. --quiet::: do not output the names, sizes, byte counts, index areas, or bit ratios of units as they are processed. 4. 見出し部はASCII文字の等号「=」を使います = 見出しレベル1 == 見出しレベル2 以下3、4、…と続きます。 5. 罫線(横方向の線)はASCII文字のハイフン三つ'---'を使います。 6. 文中で以下のようなマークアップもできます。 イタリック体 _italic_:: \_word_ もしくは \text ボールド体 *bold*:: \*word* もしくは \text タイプライター体 +typewriter+:: \+word+ もしくは \text それぞれ2つ形式がありますが、wordの方は単語を囲うことしかできません。 単語というのは、アルファベットの大文字および小文字とアンダースコアー のみから構成された文字列です(よって日本語では使えません)。また、これらの マークアップ記号の前に「\」という文字を置くと、マークアップが抑制されます。 上の表は以下のようにすれば作れます。 イタリック体 _italic_:: \_word_ もしくは \text ボールド体 *bold*:: \*word* もしくは \text タイプライター体 +typewriter+:: \+word+ もしくは \text 7. コメント内のクラス名やソースファイルの名前やメソッド名(アンダースコアー を含んでも良いし「#」が前に付いていても良い)は、自動的にリンクが張られます。 8. http:、 mailto:、 ftp:、 www. で始まるテキストはウェブへのリンクだと 判別されます。外部の画像ファイルを参照している場合は に変換 されます。link:で始まる場合はローカルファイルへのリンクであるとみなし、 --opで指定したディレクトリからの相対パスとなります。 label[url]の形式でもハイパーリンクが張れます。この場合は lavelが表示され、urlがリンク先となります。label が複数の単語を含んでいる場合(日本語の場合はこっちを使ってください)、 中括弧を使い、{multi word label}[url]としてください。 9. メソッドのパラメータは抜きだされ、ドキュメントのメソッド記述のところに 出力されます。メソッドが +yield+を呼んでいる場合は、yieldに渡されている パラメータもそこに出力されます。 def fred ... yield line, address 上のようなメソッド定義に対して、以下の出力が得られます。 fred() { |line, address| ... } メソッド名の直後に':yields: ...'を含むコメントを書くと、 この出力を上書きできます。 def fred # :yields: index, position ... yield line, address 上のようにするとお、以下の出力になります。 fred() { |index, position| ... } 10. ':yield:'はドキュメント修飾子の一例です。以下の修飾子は修飾しようとしている 部分の直後に書きます。ほかにも以下のようなものがあります。 [:nodoc:[all]] 指定した要素をドキュメントに含めません。クラスやモジュール を指定した場合、それに直接含まれるメソッドやエイリアスや 定数や属性も省略されます。しかし、デフォルトでは、指定した モジュールやクラスに含まれるモジュールやクラスはドキュメントに 含まれます。これをオフにしたい場合は +all+ 修飾子を 加えます。 module SM #:nodoc: class Input end end module Markup #:nodoc: all class Output end end 以上のコードでは、SM::Inputのドキュメントのみが出力 されます。 [:doc:] 指定したメソッドや属性を強制的にドキュメントに含めます。 これは例えば特定のプライベートメソッドをドキュメントに含めたい 場合に便利です。 [:notnew:] これはインスタンスメソッドの +initialize+ にのみ適用できます。 通常、RDocはinitializeメソッドのドキュメントやパラメータを 実際にはクラスメソッドnewのものと仮定し、initializeの代わりに newを出力します。:notnew:修飾子はこれを止めさせます。initialize メソッドはprotectedなので、コマンドラインで-aを指定するなどしな い限り、initializeメソッドに関するドキュメントは出力されないこと に注意してください。 11. 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) ... 12. コメント部には他にも以下の命令を含めることができます。 [:section: title] 新しいセクションを開始します。:section:の後ろに置いた タイトルはそのセクションの見出しとなります。そして、コメントの 残りの部分はそのセクションの導入文となります。その後ろのメソッド、 エイリアス、属性、クラスはこのセクションに含まれます。:section: 命令の前に何行かあってもかまいません。それらはドキュメントには 含まれず、またそれとまったく同じ内容の行がブロックの終端にあった場合、 それも取り除かれます。そのため、以下のような装飾をすることが できます。 # ---------------------------------------- # :section: My Section # This is the section that I wrote. # See it glisten in the noon-day sun. # ---------------------------------------- [call-seq:] デフォルトではメソッドの引数やyieldの引数をパースして出力しますが、 これを指定した次の行から次の空行までをメソッド呼び出し列と解釈し、 出力をそこに書かれたように変更します。 [:include:filename] 指定した場所に指定したファイルを挿入します。ファイルを探す ディレクトリは--includeで指定したものとカレントディレクトリ です。挿入されるファイルは:include:命令を置いたのと同じだけ インデントされます。 [:title:text] ドキュメントのタイトルを指定します。コマンドラインの--titleパラメータ と同じ働きをします。(コマンドラインでの指定のほうが優先されます) [:enddoc:] 以降の内容を一切ドキュメントに出力しません。 [:main:name] コマンドラインの--mainパラメータと同じ働きをします。 [:stopdoc: / :startdoc:] ドキュメント要素(クラス、メソッドなど)をドキュメントに含めるかど うかを制御します。例えば、あるクラスにドキュメントに出力したくない 定数があるとすると、その前に:stopdoc:を置き、後ろに :startdoc:を置きましょう。もし:startdoc:を置かな ければ、そのクラス、モジュール全体がドキュメントに出力されなくなり ます。 --- markup/simple_markup.rbも見てください。 = Other stuff Author:: Dave Thomas Requires:: Ruby 1.8.1 or later License:: Copyright (c) 2001-2003 Dave Thomas. Released under the same license as Ruby. == Warranty 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. このソフトウェアは、商業的適正を保証するほのめかしや ある特定の目的への適合性を含む一切の保証無しに、「あるがまま」で提供する。 = この翻訳について この文章は大林一平が翻訳しました。翻訳の内容に疑問がある 場合は、原文を参照してください。また、原文を見てもよくわからない場合は、 RDocを実際に動かしてみるか、ソースコードを見るかしてください。