ruby - rdoc、darkfish 和 :call-seq: 标签

Question

我正在用 rdoc 记录一个 Ruby 项目，我发现了 darkfish rdoc 格式化程序。我真的很喜欢它，但:call-seq:标签不再有效。相反，它将文字字符串:call-seq:放入文档中，然后将调用序列本身格式化为代码块。我不想只从我的代码中取出所有 :call-seq: 块，因为我的大部分文档都需要引用:call-seq:块中给出的实例名称和参数名称。有没有其他人有这个问题？我该怎么办，有没有解决方法？我很确定:call-seq:当我使用默认格式化程序时，标记之前工作，但我无法确定，因为我无法弄清楚如何返回生成原始格式（调用 rdoc 时除了文件之外没有参数现在会生成 darkfish 输出，即使我删除了 doc 文件夹！）有谁知道如何解决这个问题？

Answer 1

我强烈建议从 rdoc 转移到YARD。它本身不支持旧的 call-seq，但它有标签，尤其是@overload标签将更好地取代 call-seq。rubydoc.info上的所有文档也是使用 YARD 生成的。

以下是 YARD 文档中 @overload 的示例：

# @overload set(key, value)
#   Sets a value on key
#   @param [Symbol] key describe key param
#   @param [Object] value describe value param
# @overload set(value)
#   Sets a value on the default key `:foo`
#   @param [Object] value describe value param
def set(*args)
end