YARD macro を使った Rails scope のドキュメントの書き方

YARD を使って、rails の scope のドキュメントを書こうとした時に、色々試行錯誤したのでメモ。

macro を使わない方法

# @!group Scopes はお好みで。

一般的な DSL 的な書き方にドキュメントをつける時の書き方。

class Post < ApplicationRecord
  # @!group Scopes

  # @!method active
  #   @!scope class
  #   @return [ActiveRecord::Relation]
  scope :active, -> { where(status: 'active') }

  # @!method nonactive
  #   @!scope class
  #   @return [ActiveRecord::Relation]
  scope :nonactive, -> { where.not(status: 'active') }

  # @!method status(status)
  #   @!scope class
  #   @param [String] status
  #   @return [ActiveRecord::Relation]
  scope :status, ->(status) { where(status: status) }

  # @!endgroup
end

macro を使った方法

同じようなドキュメントを書きまくる時に省力化出来るマクロを使った場合。

一番最初にマクロを定義してあげれば、以降同じメソッドを使ったものは自動的にドキュメントを認識して書いてくれるし、必要に応じて @ タグを追加できる。

class Post < ApplicationRecord
  # @!group Scopes

  # @!macro [attach] scope
  #   @!method $1
  #   @!scope class
  #   @return [ActiveRecord::Relation]
  scope :active, -> { where(status: 'active') }

  scope :nonactive, -> { where.not(status: 'active') }

  # @overload status(status)
  #   @param [Symbol] status
  scope :status, ->(status) { where(status: status) }

  # @!endgroup
end

HTML

HTML の出力結果はどちらも同じで、下記のような形になる。

# @!group Scopes 宣言を入れておくと、 Class Method Summary ではなく、 Scopes にサマリーがまとまって表示される。

試行錯誤した点

• @!macro の宣言をリポジトリ全体のどこか１箇所だけでできないか試したけどダメだった。わかる人いたら教えてください！
• guard 使って実行すると微妙に挙動が変わるところがあってハマる
• @!macro を使う場合 @!methodo ではメソッドの宣言を上書きできなくて、@overload 使うと出来ることに気がつくのに時間がかかった

参考

File: Tags Overview — Documentation for yard (0.9.12)