用 YARD 记录“splatted”参数的最佳方法是啥？ [关闭]

Posted 2023-02-21

【中文标题】用 YARD 记录“splatted”参数的最佳方法是啥？ [关闭]

【英文标题】：Best way to document "splatted" parameter with YARD? [closed]用 YARD 记录“splatted”参数的最佳方法是什么？ [关闭]

【发布时间】：2015-08-05 15:02:31

【问题描述】：

我有一个方法应该接受任何类的 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。

【参考方案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

【讨论】：

我更新了我的问题，使其更加具体。 Array<Object> 的唯一问题是它暗示一个空的参数列表是可以接受的。 @overload 似乎更多的是用于指定具有不同类型参数的不同方法调用。

我仍然认为overload 将是最合适（和可用）的标签，特别是因为没有技术 原因该方法不能接受空列表（从方法定义的角度来看） - 它的文档看起来非常合适：rubydoc.info/gems/yard/file/docs/Tags.md#overload。如果您将方法定义更改为 my_push(first_object, *more_objects) 之类的东西，然后将它们组合并展平会怎样。不漂亮，我承认，但确实得到了可执行的数量……

我看到@param [Array] 的问题是 splat 将一个非 splatted Array 参数包装到一个数组中：def push3(*args); args.inspect end; push3([]) # => [[]] Edit：我完全无法说服 SO 格式化多行注释块