YARD 如何记录 Array<String> 类型的 @param 也可以是空白数组？

Question

以下是接受字符串数组或空白数组 ([]) 的方法片段：

# @param [Array<String>] bar
def foo(bar)
  if bar.empty?
    # Do this
  else
    # Do that
  end
end

我觉得这个@param 类型有点误导。

是否有更好的方法来显式记录空白数组用例？

Answer 1

在你的情况下，如果你知道预期的参数是一个字符串数组，那么 [Array<String>] 就足够了 (IMO) @param。可能改变的是 return 值，无论参数是否为空，因为你可以按照 docs:

中提到的那样做

Describes the return value (and type or types) of a method. You can list multiple return tags for a method in the case where a method has distinct return cases. In this case, each case should begin with “if …”.

以你的例子为例：

# @param bar [Array<String>]
# @return [TypeX] if bar is empty
# @return [TypeY] if bar is not empty
def foo(bar)
  ...
end

Answer 2

接受任意长度的数组显然意味着接受长度为零的数组。这很明显，不需要记录。

现在，如果该方法在传递一个空数组时做了一些完全不同和意外的事情，这种行为可以记录在单独的 overload (which seems to be partially supported by RubyMine)。

尽管如此，如果该方法根据其参数执行两种完全不同的操作，那么人们可能会问为什么这首先不是两种不同的方法。

YARD 如何记录 Array<String> 类型的 @param 也可以是空白数组？

YARD how to document a @param of Array<String> type which could also be a blank array?

ruby

rdoc

yard