使用 YARD 记录宏生成方法的参数

Question

输入以下内容：

class A
  # @!macro [attach] add_setting
  #   @!attribute [rw] 
  #   @!method =(value)
  def self.add_setting(setting)
  end

  # @param value [String] Hexadecimal representation of color
  add_setting :color
end

YARD 0.9.12 生成以下警告（自 ~> 0.8 以来新增）：

[warn]: @param tag has unknown parameter name: value
    in file `test.rb' near line 9

构建此文档以避免警告的正确方法是什么？（此模式用于 rspec。）

Answer 1

rspec 使用此文档是正确的，您可以看到他们指定使用定义的 macro

# @macro [attach] add_setting
#   @!attribute [rw] 
#   @!method =(value)
# .....
# @macro add_setting
# Run examples over DRb (default: `false`). RSpec doesn't supply the DRb
# server, but you can use tools like spork.
add_setting :drb

如果您注意到 @macro add_setting 声明，这会告诉 yard 在记录此方法时使用 add_setting macro。在这种情况下 </code> 表示 <code>drb 因此它将记录 drb 属性。（不是个别 getter/setter 方法）

如您所见，他们在记录这些方法时没有声明数据类型，因为这些类型可能因记录的不同方法而异。相反，他们在方法的描述中指定了默认值。

选项 1（不确定为什么有效）

只需定义 getter 和 setter 而不是使用看起来像

的 !@attribute 声明

class A
  # @!macro [attach] add_setting
  #   @!method 
  #     @return [Object] the  of the a 
  #   @!method =(value)
  def self.add_setting(setting)
  end
  # @param value [String] Hexadecimal representation of color
  add_setting :color
end

@return 很重要，否则警告会返回

选项 2

如果你真的想要这个功能，你可以使用 @overload，它看起来像

class A
  # @!macro [attach] add_setting
  #   @!method 
  #     @return [Object] the  of the a
  #   @!method =(value)
  def self.add_setting(setting)
  end
  # @overload color=(value)
  #   @param value [String] Hexadecimal representation of color
  # @macro add_setting
  add_setting :color
  add_setting :name
end

这将导致 name 和 color 的 getter 方法被记录为：

名称 => 对象
- Returns 名字
颜色 => 对象
- Returns a

但是 setter 方法看起来像

名称=（值）=> 对象
color=(value) => 对象
- 参数：
- value(String) -- 颜色的十六进制表示

因为我们超载了 color=.

话虽这么说，但这并不能真正帮助您，因为它可能包括单独记录这些方法。

其他选项：

忽略警告
全部警告完全-q
检查这个 Thread

使用 YARD 记录宏生成方法的参数

Documenting parameters for macro generated methods with YARD

ruby

yard