ruby - 用 YARD 记录“splatted”参数的最佳方法是什么？

Question

我有一个方法应该采用任何类的 1+ 个参数，类似于Array#push：

def my_push(*objects)
  raise ArgumentError, 'Needs 1+ arguments' if objects.empty?
  objects.each do |obj| 
    puts "An object was pushed: #{obj.inspect}"
    @my_array.push obj
  end
end

使用 YARD 语法记录方法参数的最佳方式是什么？

编辑：

我意识到我最初的问题有点含糊不清，并没有完全说明我在寻找什么。

一个更好的问题是，当使用 splatted 参数时，在 YARD 中指定方法的数量（在这种情况下为 1-∞）的最佳方法是什么？我知道我可以在文本中指定它，但似乎应该有一个标签或类似的东西来指定 arity。

Answer 1

YARD 的创建者 lsegal 指出，适当的做法是@overload为预期的调用提供一个。但是，在类似方法的情况下，这并不能真正提供太多的清晰度Array#push。

我建议您使用@param标签并Array<Object>用作参数类型或提供一个@overload看起来不错的。

这是两者的比较：

class Test
  # A test method
  #
  # @param [Array<Object>] *args Any number of Objects to push into this collection
  # @return nil
  def push(*args); end

  # Another test method
  #
  # @overload push2(obj, ...)
  #   @param [Object] obj An Object to push
  #   @param [Object] ... More Objects
  def push2(*args); end
end