ruby-reference-manual:108
From: Minero Aoki <aamine@l...>
Date: Wed, 11 Oct 2006 23:52:24 +0900 (JST)
Subject: [ruby-reference-manual:108] 記述フォーマット (rev.2)
青木です。
クラスリファレンスの記述フォーマットに関するドキュメントを送ります。
同じものが Subversion レポジトリの refm/api/FORMAT に入れてある
ので、最新版が必要なときはそっちを見てください。
--
青木峰郎
= 記述フォーマット
ファイルのフォーマットは RD ベースです。
ただし、厳密にパースできるように制限を増やしてあります。
== ファイルの構造
新リファレンスではライブラリごとにファイルを分割します。
各ファイル (== ライブラリの記述) は以下のような構造をしています。
require ライブラリ名
require ライブラリ名
：
：
<ライブラリのドキュメント>
<レベル1ブロック>
<レベル1ブロック>
：
：
ファイル冒頭では、「このライブラリを require したとき、同時に
使えると期待していいライブラリ」を記述します。文法は
「require ライブラリ名」です。この require 行はいくつ書いても
構いません (ゼロ個でも構いません)。
続いてライブラリ自体のドキュメントを書きます。これは省略可能です。
最後に、以下に述べる「レベル 1 ブロック」を任意の回数記述します。
「レベル 1 ブロック」はクラスやモジュールの記述です。
== レベル 1 ブロック
レベル 1 ブロックはクラスやモジュールを記述します。
レベル 1 ブロックは以下のような構造をしています。
= class クラス名 < スーパークラス名
include モジュール名
include モジュール名
：
：
<クラスのドキュメント>
<レベル2ブロック>
<レベル2ブロック>
：
：
レベル 1 ヘッダ (「=」) には以下の種類があります。
* class クラス
* module モジュール
* object オブジェクト (ほぼ ARGF と ENV 専用)
* reopen 既存クラスへのメソッドの追加
* redefine 既存メソッドの再定義 (jcode, mathn など)
ヘッダの直後には、そのクラスやモジュールが include している
モジュールを「include モジュール名」で記述します。include は
いくつ書いても構いません。
続いてクラス自身のドキュメントを書きます。省略可能です。
クラスのドキュメントでヘッドラインを使いたいときは
レベル 3 (===) 以上にしてください。
最後に「レベル 2 ブロック」を任意の回数だけ書きます。
「レベル 2 ブロック」はメソッドのグループです。
== レベル 2 ブロック
レベル 2 ブロックは特定の種類のメソッドのグループを表現します。
レベル 2 ブロックは以下のような構造をしています。
== Singleton Methods
<メソッドエントリ>
<メソッドエントリ>
：
：
レベル 2 ヘッダ (「==」) には以下の種類があります。
: Singleton Methods または Class Methods
public な特異メソッド
: Private Singleton Methods
private な特異メソッド
: Protected Singleton Methods
protected な特異メソッド
: Instance Methods
public なインスタンスメソッド
: Private Instance Methods
private なインスタンスメソッド
: Protected Instance Methods
protected なインスタンスメソッド
: Module Functions
モジュール関数
: Constants
定数
: Special Variables
特殊定数 (Kernel 限定)
== メソッドエントリの文法
メソッドエントリは以下のような構造です。
---- メソッド名
---- メソッド名(引数)
---- メソッド名(引数) { .... }
<メソッドのドキュメント>
引数の形式がいくつもある場合や、alias があるときは、上記の
ように「--- メソッド名」の行を連続して書いてください。
メソッドシグネチャは Ruby での def と同じように記述します。
旧リファレンスマニュアルでは「self + other」や
「self[key] = value」のような書きかたも許容されていましたが、
新マニュアルでは認められません。
メソッドのドキュメント内でヘッドラインを使いたいときは
レベル 3 (===) 以上を使ってください。
== 通常のテキストの文法
ライブラリのドキュメント、クラスのドキュメント、メソッドの
ドキュメントでは以下に述べる共通の文法を使います。
=== 段落
通常の段落はインデントなしで書きます。
=== リスト
インデントするとリストになります。
[例]
テキスト〜
p Object.new
特殊な事情があってインデントが使えない場合は
以下の記法を使ってください。
//emlist{
リスト
//}
※ 「//emlist{」と「//}」はインデントしない
=== 箇条書き
箇条書きはインデント + '*' です。インデントなしは不可。
[例]
テキスト〜
* 項目 1
* 項目 2
* 項目 3
=== 番号付きの箇条書き
番号付きの箇条書きはインデント + (1), (2), ... です。
インデントなしは不可。
[例]
テキスト〜
(1) 項目 1
(2) 項目 2
(3) 項目 3
=== ハイパーリンク
以下のようなハイパーリンク記法が使えます。
* [[c:String]] クラス String にリンク
* [[c:File::Stat]] クラス File::Stat にリンク
* [[m:String.new]] メソッド String.new にリンク
* [[m:String#dump]] メソッド String#dump にリンク
* [[m:String#[] ]] メソッド String#[] にリンク (空白必須)
* [[m:File::SEPARATOR]] 定数 File::SEPARATOR にリンク
* [[m:$~]] 特殊変数 $~ にリンク
* [[lib:jcode]] ライブラリ jcode にリンク
* [[man:tr(1)]] man ページ tr(1) にリンク
* [[url:http://i.loveruby.net]] URL http://i.loveruby.net にリンク
=== 既存リファレンスから削除された機能
RD の (({...})), ((|...|)) はサポートしません。
bc-convert.rb を使うと自動的にすべて削除されます。
脚注とコメントも廃止されました。コメントを書きたい場合は
プリプロセッサコメント「#@# ...」を使ってください。
== プリプロセッサ
各ファイルは事前に専用プリプロセッサで処理されます。プリプロセッサ
の命令はすべて行単位で、すべて「#@」で始まります。
=== #@#
「#@#」の行はコメントです。
=== #@include
「#@include(ファイル名)」で他のファイルをテキスト的に結合できます。
「ファイル名」は #@include の書かれているファイルからの相対パスを
探します。
[例]
#@include(HTTP)
#@include(HTTPHeader)
#@include(HTTPRequest)
#@include(HTTPResponse)
=== #@since
「#@since バージョン 〜 #@end」でバージョン依存コンパイルができます。
例えば Ruby 1.8.0 以降にのみ適用される文章は以下のように記述します。
[例]
#@since 1.8.0
Ruby 1.8 以降では 〜〜
#@end
#@since 命令は #@if 命令の特殊形です。
=== #@if
「#@if(条件) 〜 #@else 〜 #@end 」でバージョン依存コンパイルが
できます。例えば Ruby 1.8.0 以降にのみ適用される文章は以下
のように記述します。
[例]
#@if (version >= "1.8.0")
Ruby 1.8 以降では 〜〜
#@end
いまのところ条件式の評価はテキトーなので、比較式 (>= とか == とか)
しか使えません。他の式が使いたいときは ML で相談してください。
--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/