YARD如何正确文档标注可传入空数组的Array<String>类型@param参数

首先明确原标注的误解根源：
@param [Array<String>] 本身的类型语义为「元素全部属于字符串类型的数组」，空数组从基础类型规则上本来就完全符合这个定义。之所以会产生误导，本质不是类型标错了，而是文档只标注了类型，没有把「空数组是方法设计时就刻意支持的合法入参、对应独立处理分支」这个预期明确传递出去，导致读代码的人会误以为空数组是没做边界校验的异常场景，不是预期的入参。

具体可落地的优化方式：

• 最通用的适配方案（兼容YARD等绝大多数Ruby文档生成工具）：保留原有类型标注，在参数的描述文本里明确补充空数组的支持场景，不需要改动类型标识本身。示例代码：

# @param bar [Array<String>] 字符串元素构成的数组，支持传入空数组 []；传入空数组时会触发空值分支的特殊处理逻辑
def foo(bar)
  if bar.empty?
    # Do this
  else
    # Do that
  end
end

• 避免无意义的冗余类型写法：不要为了强调空数组，特意把参数类型写成[Array<String>, []]的联合形式。这种写法反而会让读文档的人产生困惑，误以为入参是「要么是字符串数组、要么是单独的空数组字面量」，增加不必要的认知负担——空数组是所有元素类型数组的天然合法实例，完全不需要单独列成一个类型分支。
• 静态类型工具场景的适配：如果团队使用RBS、Sorbet这类带静态检查的Ruby类型工具，Array<String>的原生类型定义本身就兼容空数组，不需要额外修改类型规则，只需要在方法注释里把两种入参对应的行为清晰列出来即可，比如在方法头部注释补充：

  方法入参兼容两类合法场景：

  • 非空字符串数组：执行非空分支的通用处理逻辑
  • 空数组[]：执行空值分支的特殊处理逻辑

内容的提问来源于stack exchange，提问作者Nikita Fedyashev