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

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

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

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

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

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

解决方法

在您的情况下，如果您知道预期的参数是一个字符串数组，那么 [Array<String>] 对 @param 来说就足够了（IMO）。无论参数是否为空，可能会改变的是返回值，因为您可以按照 docs 中提到的那样做：

描述方法的返回值（和一个或多个类型）。你可以 在方法具有的情况下，列出方法的多个返回标签 不同的返回情况。在这种情况下，每个案例都应以“如果 ……”。

例如：

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

,

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

现在，如果该方法在传递一个空数组时执行了完全不同且出乎意料的事情，则可以将这种行为记录在单独的 overload（似乎是 partially supported by RubyMine）中。

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