h1. YARDによるドキュメントの書き方

h2. 引数関連のタグ

h3. @param

# @param [引数のクラス] 引数名 説明

引数の説明をつけるタグ。 クラスを複数指定できる場合はコンマで区切って並べる。 またクラスは省略可能。

例:

# @param [String] name 名前
def hello(name)
end

生成されるドキュメント:

- (Object) hello(name)
Parameters:

name (String) — 名前

h3. @option

# @option 引数名 [値のクラス] キー名 (ハッシュ内でキーを指定しなかった時のデフォルト値) 説明

引数がHashの場合に、ハッシュについての情報を記述するためのタグ。 まず @param でハッシュ全体についての説明を設定してから、 @option でそのハッシュにて指定するキーの名前とその説明を指定する。 1つの @param につき @option を複数指定できる。 クラス名は複数指定可で省略可能。 デフォルト値も省略することができる。

例: 引数optionsに、:name, :ageをキーとして持つハッシュを指定する場合を示す。 この場合、optionsは例えば次のようになる。

options = {:name => "John", :age => 23}
その場合のドキュメントは次のようになる。

@param [Hash] options その人の情報

@option options [String] :name 名前

@option options [Integer] :age 年齢

def set(options) end

生成されるドキュメント:

- (Object) set(options)

Parameters: options (Hash) — オプション

Options Hash (options): :name (String) — 名前 :age (Number) — 年齢

h3. @overload

# @overload メソッド名(引数)

複数の引数パターンがある場合に、それぞれのパターンを指定するタグ。 それぞれの引数に対しての説明は @overload の下にインデントをつけた @param で記述する。

例:

@overload set(name, value)

@param name セットするオプションの名前

@param value 名前に対応する値

@overload set(hash)

@param hash セットするオプションの名前をキーにしたハッシュ

def set(options) end

生成されるドキュメント:

- (Object) set(name, value)
- (Object) set(hash)

Overloads:

- (Object) set(name, value)
Parameters:
    name — セットするオプションの名前
    value — 名前に対応する値

- (Object) set(hash)
Parameters:
    hash — セットするオプションの名前をキーにしたハッシュ

h2. 場合ごとの具体例

h3. 引数にある値を指定するかどうかで他の引数に影響がある場合

例えば、あるメソッドcreate_tableの引数に指定するハッシュoptionsにて、キー:typeには:array, :hash, :patricia_trieが指定でき、:hashと:patricia_trieを指定した場合には:key_typeも指定可能になる。 このように、ある値を指定した場合としていない場合とで他の引数が指定可能かどうかが変わる場合には、:typeに指定した値ごとに@overloadで分けて書く。 @overloadを使い、:typeに:array, :hash, :patricia_trieを指定した場合それぞれのoptionsを示した状態を書く。 例えば:type => :arrayの場合は次のようになる。

@overload set(options={:type => :array})
それぞれの@overloadの中で、@param, @optionを使いoptionsの説明を書く。 :key_typeの説明は:type => :hashの場合のみに記述する。 なお、それぞれの場合において共通するキーについてもそれぞれの@overloadに書く。 そのように記述して、1つの@overloadでくくられた箇所さえ見れば他の引数についても情報が得られるようにする。 以下に例を示す。この場合、:force, :path, :typeはすべてに共通するキーである。

# @overload create_table(name, options={:type => :array}, &block)
#   :typeに:arrayを指定した場合、~~~。
#   @param options setに関してのオプション
#   @option options :force
#   @option options :path
#   @option options :type
# @overload create_table(name, options={:type => :hash}, &block)
#   :typeに:hashを指定した場合、~~~。
#   @param options setに関してのオプション
#   @option options :force
#   @option options :type
#   @option options :path
#   @option options :key_type キーのタイプを指定
# @overload create_table(name, options={:type => :patricia_trie}, &block)
#   :typeに :patricia_trieを指定した場合、~~~。
#   @param options setに関してのオプション
#   @option options :force
#   @option options :path
#   @option options :type
#   @option options :key_type (default_path) キーのタイプを指定
def create_table(name, options={:type => :array}, &block)
end

h3. 整形なしでコードを表示したい場合 「以下のコードと同様の動作をする。」としてメソッドの書き方をドキュメントに書きたいが、この場合はどう記述するか。

preを使う。@exampleタグは、そのまま実行して正しく動作するコードにのみ利用する。