用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中指定方法的arity(在这种情况下为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