rdoc、darkfish 和 :call-seq: 标签

Question

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

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