HowToWriteMethodEntry

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

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

#@# こんな感じ
--- メソッド名                  -> 返り値の型
--- メソッド名(引数)            -> 返り値の型
--- メソッド名(引数) { .... }   -> 返り値の型

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

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

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

#@# こんな感じ
--- +(other) -> String
--- []=(key, value)

と書いて下さい。また、デフォルト値付きの引数はイコールの前後にスペースを入れてください。

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

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

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

(必須) メソッドを一言で説明する文を一段落で書く。この内容は自動抽出され、「メソッドの要約」としてクラスのページに出力される。特に内容に注意が必要。
(省略可) メソッドの詳しい説明を書く。
(必須) 引数があれば、引数の情報を書く。「@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 メソッドを持たないときに発生します。
                 ↑ メソッドの選択が悪かったのでかなり無理無理な条件になってしまった

#@samplecode 例
        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
#@end

@see ![[m:String#rindex]]

@param について

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

@param には引数の

意味
制約条件

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

また、キーワード引数については、@param キーワード引数の名前説明 の形式で記述します。

#@# [例]
--- some_method(required_keyword:,  optional_keyword: "default_value",  **kw) -> ()

説明

@param required_keyword 必須のキーワード引数の説明〜〜〜。
@param optional_keyword デフォルト値のあるキーワド引数の説明〜〜〜。
@param kw 組み込みライブラリや標準添付ライブラリだとあまりないかもしれない例。

返り値の型の記述方法

メソッドシグネチャには以下のように返り値の型を必ず(MUST)記述します。定数の場合も書いてください。

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

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

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

それでうまくいかないときは "|" を使って記述例: CGI# -> 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

@raise

例外を「投げる」と書かないようにしてください。例のように「発生する」とか「発生します」とか書くようにしてください。

主にメソッド中で明示的に raise している例外を書きます。また、一般的に考えて rescue する価値のない例外を書く必要はありません。

例えばバグに起因する例外は書く必要はありません。 ArgumentError, TypeError などは @param で引数の条件がちゃんと書いてあれば不要なことが多いでしょう。

[ruby-reference-manual:334] 参照。

注意点

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

self と「自身の」という表記は self に統一する。

返り値やメソッドの説明を書くときに、「self を○○します」や「自身を○○します」といった表記が考えられますが、「self を○○します」という表記に統一してください。

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly