Question

我有一个带有可变数量参数的函数，如下所示：

def myfun(*args)
  # ...
end

所有args属于同一类型（Symbol），所以我现在记录函数，如果只有一个参数，说它可能需要多个，例如：

# this function doesn’t do anything
# @param [Symbol]: this argument does something, you can add more symbols
#                  if you want
def myfun(*args)
  # ...
end

有没有内置的方法来处理这种情况？

Answer 1

以下内容有道理，因为args在方法中是Array，但这些参数都不是Array：

# this function doesn’t do anything
#
# @param [Array<Symbol>] args these arguments do something
# @return [nil]
def myfun(*args)
  # ...
end

请注意，*已从评论中的参数名称中删除。这只是为了保持一致 - args 是Array，但*args不是。{/ p>

快速搜索显示了很多使用此样式的项目，包括Yard自己的.rb文件（例如参见source for initialize in Verifier class） - 尽管指南中未提供此约定的示例。

Answer 2

Neil Slater's answer 是我所知道的最好的非结构化参数列表。

但是对于使用 *args 接受任何一组固定的可能参数列表的方法，有 @overload。例如，对于 Enumerable#find_index，可以这样写：

# Compares each entry in _enum_ with value or passes to _block_.
# Returns the index for the first for which the evaluated value
# is non-false. If no object matches, returns `nil`.
# 
# @overload find_index(value)
#   Finds the first index of the specified value.
#   @param value [Object] the value to find
#   @return [Integer, nil] the index, or `nil` if no element matches
# @overload find_index(&block)
#   Finds the index of the first value matching
#   the specified block.
#   @yieldparam [Object] element the element to match against
#   @yieldreturn [Boolean] whether the element matches
#   @return [Integer, nil] the index, or `nil` if no element matches
# @overload find_index
#   @return [Enumerator] a new enumerator
def find_index(*args)
  # (...)
end

这将被记录为：

<块引用>

#find_index（值）⇒ 整数^?
#find_index {|元素| ... } ⇒ 整数^?
#find_index ⇒ 枚举器

将 enum 中的每个条目与值或传递给 block 进行比较。返回第一个评估值的索引是非假的。如果没有对象匹配，则返回 nil。

过载：

#find_index(value) ⇒ Integer^?

查找指定值的第一个索引。

(...等)

如何在YARD中记录具有可变数量参数的函数？

2 个答案: