用 YARD 记录 "splatted" 参数的最佳方法？

Question

我有一个方法应该接受任何 class 的 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 表示 the appropriate thing to do is provide an @overload for expected invocations。但是，对于类似 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

用 YARD 记录 "splatted" 参数的最佳方法？

Best way to document "splatted" parameter with YARD?

ruby

parameters

documentation

yard

splat