はじめに

YARDというRuby用のドキュメンテーションツールがあります。以前、Cで記述したRubyの拡張ライブラリにYARD用のドキュメントを書く方法を説明しました。今回は、Rubyで定義したメソッドの引数についてYARD用のドキュメントを書く方法を説明します。

引数を対象とする理由は、引数のドキュメントを書く機会が多いからです。ライブラリのドキュメントは、メソッドについて書くことがほとんどです。メソッドには引数があることが多いため、引数の説明を書く機会が多いのです。

この記事では、まず、YARDで使う記法について説明します。その後、引数についてのドキュメントを書くための@paramタグについて説明し、実際にRubyのコードにドキュメントを書いていきます。ドキュメントを書くごとにHTMLを生成して、@paramタグで書いたドキュメントがどのように表示されるかを確認します。

YARDのタグとディレクティブ

まず、YARDでドキュメントを書くときに使う記法を説明します。

YARDには「タグ」と「ディレクティブ」という2つの記法があります。このタグとディレクティブを使って、コメントとしてドキュメントを書きます¹。タグとディレクティブは、それぞれ次のように使います。

タグとディレクティブの詳細は公式のドキュメント（英語）に詳しく書かれているので、興味のある方はこちらをご覧ください。引数についてドキュメントを書くには、たくさんあるタグのうち@paramタグを利用します。それでは、この@paramタグについて説明します。

@paramタグ

@paramタグは「引数」というメタデータを埋め込むためのタグです。引数がどんなクラスのオブジェクトであることを期待しているか（以降、「引数のクラス」と呼ぶ）や、引数の説明を文章で書くために使います。1つの引数につき1つの@paramタグを書きます。引数が複数ある場合は複数の@paramタグを書きます。

@paramタグの書式は以下の通りです。

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

どこにどのように書けばよいかなど、実際の使い方は後ほど説明します。その前に、@paramタグの使い方を示すために使うサンプルコードを示します。このコードに対して@paramタグでドキュメントを書いていきます。

サンプルコード

以下にRubyのコードを示します。このコードに対してドキュメントを書いていきます。

このコードはextract_overageメソッドを定義しています。extract_overageメソッドは、配列と数値を引数にとり、各要素から数値より大きい数（数値が指定されない場合は20より大きい数）を集めた配列を返します。例えば、extract_overage([17, 43, 40, 56], 40)を実行すると、[43, 56]を返します。

# Returns Array containing numbers exceeding limit_age.
# For example, extract_overage([17, 43, 40, 56], 40) #=> [43, 56]
def extract_overage(ages, limit_age=20)
  ages.select do |number|
    number > limit_age
  end
end

このコードを、以降、「サンプルコード」と呼びます。

サンプルコードで定義しているextract_overageメソッドのコメントに、メソッドの説明を書いておきました²。ただし、引数についての説明は書いていません。引数についての説明はこのあと@paramタグで書いていきます。

なお、YARDはメソッド定義の直前のコメントに書いている内容をメソッド全体の説明として扱います。それを確かめるために、サンプルコードからHTMLのリファレンスマニュアルを生成してみましょう。サンプルコードをexample.rbというファイルに保存して、次のコマンドを実行することで、HTMLのリファレンスマニュアルを生成できます。

$ yardoc example.rb

生成されたリファレンスマニュアルは以下のようになります。

図の赤枠の部分を見ると、コメントに書いた説明がメソッド全体の説明としてextract_overageメソッドのところに表示されています。また、緑色の枠の部分には、メソッド全体の説明の1行目がサマリーとして表示されています。

@paramタグの使い方

それでは、@paramタグで引数のドキュメントを書きましょう。ここからは、サンプルコード内のextract_overageメソッドの中身を省略します。これは、ドキュメントを書く場所をわかりやすくするためです。メソッドの中身を省略すると以下のようになります。

# Returns Array containing number exceeding limit_age.
# For example, extract_overage([17, 43, 40, 56], 40) #=> [43, 56]
def extract_overage(ages, limit_age=20)
end

1つ目の引数のドキュメントを書く

ではまず、1つ目の引数であるagesについてのドキュメントを書きます。@paramタグの書式を再掲します。

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

1つ目の引数agesについて記述するので、引数名はages、 引数のクラスはArrayとなります。説明は「numbers checked if they exceeded from limit_age.」となります。

次に、@paramタグを書く場所を説明します。@paramタグは、メソッド全体の説明と同じく、メソッド定義の直前のコメントに書きます。メソッド全体の説明の下に空のコメント行を1行入れ、その下に書くとよいでしょう。このように書くと、コードに書かれたドキュメントを読むときに理解しやすくなります³。この順序でドキュメントを書くと、ドキュメントを読む人はメソッド全体の説明を読んでから個々の引数の説明を読めるからです。全体を把握してから細部を見る、という順序で読むことができ、メソッドを理解しやすくなります。

それでは、@paramタグで引数agesの説明を書きます。

# Returns Array containing numbers exceeding limit_age.
# For example, extract_overage([17, 43, 40, 56], 40) #=> [43, 56]
#
# @param ages [Array] numbers checked if they exceeded from limit_age.
def extract_overage(ages, limit_age=20)
end

上記のコードからHTMLのリファレンスを生成すると次のようになります。図の赤枠のところが今回追加された説明です。

引数agesについての説明が追加されています。

2つ目の引数のドキュメントを書く

次に2つ目の引数のlimit_ageについても同じように書いていきましょう。

1つの@paramタグで1つの引数の説明を書きます。引数が複数ある場合はその数だけ@paramタグを使います。コメントに書かれたドキュメントを読むときには、似たような情報がまとまっていた方が読みやすいので、引数のドキュメントは並べて書くのがよいでしょう。

1つめの引数から順番にドキュメントを書くとメソッド定義と対応がとりやすくなるので理解しやすくなります。これはコードに書かれたドキュメントを読むときもHTMLのリファレンスマニュアルを詠むときも同様です。HTMLのリファレンスマニュアルでは、同じタグ（ここでは@paramタグ）は書かれた順番に表示されるからです。

では、引数limit_ageについてのドキュメントを書きます。

# Returns Array containing numbers exceeding limit_age.
# For example, extract_overage([17, 43, 40, 56], 40) #=> [43, 56]
#
# @param ages [Array] numbers checked if they exceeded from limit_age.
# @param limit_age [Integer] limit_age limit used to extract
#   bigger ages than it.
def extract_overage(ages, limit_age=20)
end

追加した@paramタグでは、説明の文章を折り返しています。# bigger ...の行です。@paramタグで書くドキュメントを途中で折り返すときは、@paramタグの開始行よりもインデントしてください。インデントすると、YARDはインデントされた行を前の行の継続行として扱います。

それでは、上記のコードからHTMLのリファレンスを生成しましょう。次のようになります。図の赤枠のところが今回追加した説明です。

limit_ageについての説明が追加されています。折り返された説明は1つの文として扱われています。

extract_overageメソッドを呼び出すときに引数limit_ageを省略すると自動的に20がデフォルト値として使用されますが、HTMLのリファレンスマニュアルにはそのことが(default to: 20)として表示されています。これは、YARDがメソッド定義から判断して表示しています。そのため、明示的にドキュメントに書かなくてもデフォルト値が表示されます。

ここでは以下のことを説明しました。

• 説明が長くなるときは折り返してインデントをすること
• デフォルト値はYARDが自動的に判断してくれること

まとめ

今回は、Rubyで定義したメソッドの引数にYARD用のドキュメントを書く方法を説明しました。ドキュメントを書くことで、ユーザーがソフトウェアを使いやすくなります。それだけではなく、開発者としてもよいソフトウェアを書くのに役立つのでドキュメントを書いてみてはいかがでしょうか。

次回は、@returnタグを使って戻り値についてドキュメントを書く方法を説明する予定です。

ツイートする

フォローする