rubyのキーワード引数のあるメソッドをYardで書く方法

内容

意外とググっても出なかったのでメモ。

rubyのキーワード引数（keyword parameters）があるメソッドのパラメータドキュメントをYardで書く場合どうするか。

答え

rubyでよく使われるHashをオプションとして引数に渡す場合、下記のように @option が使われるが、

# @param [Hash] opts the options to create a message with.
# @option opts [String] :subject The subject
# @option opts [String] :from ('nobody') From address
# @option opts [String] :to Recipient email
# @option opts [String] :body ('') The email's body
def send_email(opts = {}) end

キーワード引数の場合は、普通に @param を利用するのが正解のようだ。

Note: For keyword parameters, use @param, not @option.

なので、下記のようになる。

# @param　subject [String] The subject
# @param from [String] ('nobody') From address
# @param to [String] Recipient email
# @param body [String] ('') The email's body
def send_email(subject: nil, from: nil, to: nil, body: nil) end