🦔
RailsのYARD形式について
YARDとは
Rubyで書かれたコードの解説書を自動的に作成するツールです。
コード内に説明コメントを書かれていることがよくありますが、
YARDはこのコメントを読み取って、それらを集めて解説書を作成します。
YARD形式
Rubyのプログラム内で使用されるコメントを記述する際の慣例や規則のことです。
ex)
メソッドやクラスの説明、引数や戻り値の説明、使用例など
@paramタグはメソッドの引数を説明、@returnタグはメソッドの戻り値を説明
# 実際の例
例えば、YARDのタグは以下のものがあります。(これ以外もあります。)
参考資料を見るとこんなものがあるみたいです。
(データ/型/名前/説明の書き方)
# @タグ [型] <名前> <説明>
(例)
# @param [Array] arr表示したい配列
# @return [String] 空白を除去した文字列
@params メソッドに渡す引数の説明
@raise メソッドで発生しえる例外クラスの説明
@return メソッドの返り値の説明
引用 https://morizyun.github.io/blog/yard-rails-ruby-gem-document-html/index.html
# これはサンプルのメソッドです。
#
# @param input [String] 入力文字列
# @param count [Integer] 処理回数
# @return [String] 処理された文字列
def sample_method(input, count)
# メソッドの本体
end
YARDタグ
以下がYARDの一覧です。
| タグ | 説明 |
|---|---|
| @todo | 未完了のタスクや改善すべき点 |
| @param | メソッドの引数 |
| @return | メソッドの戻り値 |
| @note | 注釈や特記事項 |
| @see | 他の関連するリソースや参照先 |
| @example | コードの使用例 |
| @yield | メソッドがブロックを受け取る場合、そのブロックのドキュメントを提供 |
| @raise | メソッドが例外を発生させる可能性がある場合、その例外の種類と条件を説明 |
YARD形式のコメントを追加することが推奨
一般的には以下のような時に、使われるみたいです。
メソッドが外部に公開される場合やAPIドキュメントを生成する必要がある場合。
メソッドの振る舞いや目的が複雑である場合。
メソッドの使用方法や引数の説明が必要な場合。
PHPバージョンは？
PHPだと、PHPDocがあるみたいです。す。
資料
ChatGPT
Discussion