るりまWiki: HowToWriteMethodEntry

2009-10-30 17:33:03 +0900 (136d); rev 28

メソッドシグネチャの文法

メソッドシグネチャ (メソッド名と引数の記述) は以下のように書きます。

  --- メソッド名                  -> 返り値の型
  --- メソッド名(引数)            -> 返り値の型
  --- メソッド名(引数) { .... }   -> 返り値の型

  <メソッドのドキュメント>

引数の形式がいくつもある場合や、alias があるときは、上記のように「--- メソッド名」の行を連続して書いてください。

メソッドシグネチャは Ruby での def と同じように記述します。旧リファレンスマニュアルでは「self + other」や「self[key] = value」のような書きかたも許容されていましたが、新マニュアルでは認められません。それぞれ、

--- +(other)
--- []=(key, value)

と書いて下さい。

メソッドのドキュメント内でヘッドラインを使いたいときはレベル 3 (===) 以上を使ってください。

メソッドのドキュメントでの規則

メソッドのドキュメントは以下の項目を、この順番で記述します。

(必須) メソッドを一言で説明する文を一段落で書く。この内容は自動抽出され、「メソッドの要約」としてクラスのページに出力される。特に内容に注意が必要。
(省略可) メソッドの詳しい説明を書く。
(必須) 引数があれば、引数の情報を書く。「@param pattern 検索するパターン」などと書く。
(省略可) 返り値の情報を書く。「@return ...」などと書く。
(省略可) 発生する例外を書く。「@raise ArgumentError ...」などと書く。
(省略可) その他の注意事項を書く。
(省略可) 使用例を書く。
(省略可) 他のメソッドなどへの参照を書く。「@see [[メソッド名]], [[クラス名]] 」などと書く。

[例]

--- index(pattern, pos = 0)    -> Integer | nil

文字列のうちインデックス pos 以降の部分から
パターン pattern を検索し、そのインデックスを返します。
pattern が見付からなかったときは nil を返します。

必要ならここに詳しい説明。必要ならここに詳しい説明。必要ならここに詳しい説明。
必要ならここに詳しい説明。必要ならここに詳しい説明。必要ならここに詳しい説明。
必要ならここに詳しい説明。必要ならここに詳しい説明。必要ならここに詳しい説明。

必要ならここに詳しい説明。必要ならここに詳しい説明。必要ならここに詳しい説明。
必要ならここに詳しい説明。必要ならここに詳しい説明。必要ならここに詳しい説明。

@param pattern   検索するパターンです。
                 正規表現、文字列、文字コードを示す 0 から 255 の整数のいずれかを指定します。
@param pos       検索を始めるインデックスです。整数で指定します。
                 負の数を指定したときは文字列の末尾から数えたインデックスとみなします。
@return          見付かった場合は要素のインデックスを、見付からなかったときは nil を返します。
@raise ArgumentError
                 上記以外の引数を渡し、かつそのオブジェクトが
                 to_s メソッドを持たないときに発生します。
                 ↑ メソッドの選択が悪かったのでかなり無理無理な条件になってしまった

        p "strstrstr".index(/str/)       # => 0      ← 引数 pattern の例
        p "strstrstr".index("str")       # => 0
        p "strstrstr".index(?s)          # => 0

        p "strstrstr".index(/xxx/)       # => nil   ← 検索が失敗したときの例
        p "strstrstr".index("xxx")       # => nil
        p "strstrstr".index(?x)          # => nil

        p "strstrstr".index(/str/, 0)    # => 0    ← pos 引数の例
        p "strstrstr".index(/str/, 1)    # => 3
        p "strstrstr".index(/str/, 3)    # => 3
        p "strstrstr".index(/str/, 4)    # => 6

        p "strstrstr".index(/str/, -1)   # => nil    ← 負の pos 引数の例
        p "strstrstr".index(/str/, -2)   # => nil
        p "strstrstr".index(/str/, -3)   # => 6

@see [[m:String#rindex]]

@param について

引数がある場合、@param は必須とします。本文の繰り返しになっても良い。

@param には引数の

意味
制約条件

を書く。例えば String#index(pattern, pos = 0) の pos なら「意味」とは「検索を開始する位置」であり、制約条件は「整数」です。制約条件は「型」とほぼ同じです。

返り値の型の記述方法

メソッドシグネチャには以下のように返り値の型を必ず(MUST)記述します。

任意の型の場合、「object」
x の配列は [x]
インデックスによって型が違う配列は [x, y, z]
x から y のへのハッシュは {x => y}
true, false, nil, self を返すときはそのまま
真偽値を返す場合は「bool」
多値も配列扱い
返り値が不定の場合は、「-> ()」と書く。
代入式の場合には省略する。

メソッドが複数の型を返す場合

複数の型の値を返すときは原則としてシグネチャを分けます。

それでうまくいかないときは "|" を使って記述

      例:  CGI#[](name) -> String | [String]

ただし x オブジェクトと nil で成功・失敗を表す場合は「x | nil」を使う

     例:String#index(略) -> Integer | nil

以上のルールで記述できない場合は「object」と書いて文章で説明

返り値の型の記述の例

--- Enumerable#all? {...} -> bool
--- Enumerable#map {...} -> [object]
--- Enumerable#each_with_index {...} -> self
--- Array#pop -> object
--- Array#size -> Integer
--- Array#[]=(nth, val)   <= 省略
--- Thread.critical=(state)  <= 省略
--- String#+(...) -> String
--- String#capitalize! -> self | nil
--- Test::Unit::Assertions#assert(val) -> ()
--- Digest::MD5.new() -> Digest::MD5

注意点

メソッドエントリを実際に書くうえで、間違いやすい点を列挙しておきます。 ClassReferenceManualFormat に関するものも含みます。

@param などを行継続する場合はインデントする

@param pattern   検索するパターンです。
                 正規表現、文字列、文字コードを示す 0 から 255 の整数のいずれかを指定します。

これはOKですが、

@param pattern   検索するパターンです。
正規表現、文字列、文字コードを示す 0 から 255 の整数のいずれかを指定します。

これだと二行目を続きだとみなしてくれません。

Kernelのメソッドはモジュール関数

[[m:Kernel.puts]]
[[m:Kernel#puts]]

は間違いです。正しくは以下です。

[[m:Kernel.#puts]]

リンクや宣言の使用範囲

@seeなど@系の宣言やハイパーリンクはかけるところが制限されています。よって

==== [[c:Proc]] の内容

などという書き方はできません。また、メソッドのドキュメント以外の場所（クラスのドキュメントなど）で@系のものを書くことはできません。

-> ()の用法

返り値が不定の場合は「-> ()」と書きますが、単に任意の型が返ってくる場合にも「-> ()」を使ってしまっているケースが見受けられます。その場合は「-> object」です。

not boolean

真偽値を返す場合は「bool」です。「boolean」ではありません。

返り値のnilは後ろ

例えば成功するとString, 失敗するとnilを返すメソッドの返り値は -> String|nil nilを後ろに書く。

:nodoc:

nodoc が付いているなどの理由でリファレンスを書かないメソッドは #@# でコメントアウトしておく。別の人が見たときに困らないため。

system revision 1.162