File: rdoc.ja

Path:rdoc.ja
Modified:Sat Feb 12 21:38:04 JST 2005

RDOC - Ruby Documentation System

このパッケージは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は以下が指定できます。

—accessor 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"オプションは 正しい出力ができません(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/<ver>/siteに、—ri-systemで $datadir/ri/<ver>/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
    

    どちらの形式のラベル付きリストでも、ラベルと同じ行から記述部を書き始めた 場合は、その記述部と同じインデントでひとかたまりとなります。 また、ラベルの次の行から記述部を書き始めることもできます。ラベル部の文章が 長くなるならこうしたほうが良いかもしれません。つまり以下の例のどちらでも 良いということです。

       <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.
    
  4. 見出し部はASCII文字の等号「=」を使います
       = 見出しレベル1
       == 見出しレベル2
    

    以下3、4、…と続きます。

  5. 罫線(横方向の線)はASCII文字のハイフン三つ’—’を使います。
  6. 文中で以下のようなマークアップもできます。
    イタリック体 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>
    
  7. コメント内のクラス名やソースファイルの名前やメソッド名(アンダースコアー を含んでも良いし「#」が前に付いていても良い)は、自動的にリンクが張られます。
  8. http:、 mailto:、 ftp:、 www. で始まるテキストはウェブへのリンクだと 判別されます。外部の画像ファイルを参照している場合は <IMG..> に変換 されます。link:で始まる場合はローカルファイルへのリンクであるとみなし、 —opで指定したディレクトリからの相対パスとなります。

    label[url]の形式でもハイパーリンクが張れます。この場合は lavelが表示され、urlがリンク先となります。label が複数の単語を含んでいる場合(日本語の場合はこっちを使ってください)、

  中括弧を使い、<em>{multi word label}[</em>url<em>]</em>としてください。
  1. メソッドのパラメータは抜きだされ、ドキュメントのメソッド記述のところに 出力されます。メソッドが yieldを呼んでいる場合は、yieldに渡されている パラメータもそこに出力されます。
       def fred
         ...
         yield line, address
    

    上のようなメソッド定義に対して、以下の出力が得られます。

       fred() { |line, address| ... }
    

    メソッド名の直後に’:yields: …’を含むコメントを書くと、 この出力を上書きできます。

       def fred      # :yields: index, position
         ...
         yield line, address
    

    上のようにするとお、以下の出力になります。

        fred() { |index, position| ... }
    
  2. ’: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メソッドに関するドキュメントは出力されないこと に注意してください。
  3. 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)
           ...
    
  4. コメント部には他にも以下の命令を含めることができます。
    :section: title
    新しいセクションを開始します。:section:の後ろに置いた タイトルはそのセクションの見出しとなります。そして、コメントの 残りの部分はそのセクションの導入文となります。その後ろのメソッド、 エイリアス、属性、クラスはこのセクションに含まれます。: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 <dave@pragmaticprogrammer.com>
Requires:Ruby 1.8.1 or later
License:Copyright © 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.

このソフトウェアは、商業的適正を保証するほのめかしや ある特定の目的への適合性を含む一切の保証無しに、「あるがまま」で提供する。

この翻訳について

この文章は大林一平<ohai@kmc.gr.jp>が翻訳しました。翻訳の内容に疑問がある 場合は、原文を参照してください。また、原文を見てもよくわからない場合は、 RDocを実際に動かしてみるか、ソースコードを見るかしてください。

Classes