使用 Yardoc 记录 def_delegators答案

【问题标题】：Documenting def_delegators with Yardoc使用 Yardoc 记录 def_delegators
【发布时间】：2013-02-15 09:09:55
【问题描述】：

我有一个类使用来自Forwardable 模块的def_delegators 方法。我还没有找到让Yardoc 为其输出文档的方法。我尝试过使用macro，但它不会为这些特定方法输出任何内容（文件中的其他所有内容都很好，并且没有错误），而且我有几个不同长度的def_delegators。

例如

class A
  extend Forwardable
  # other code…

  # @!macro
  #   @see Array#$1
  #   @see Array#$2
  #   @see Array#$3
  def_delegators :@xs, :size, :<<, :blah # …

如果有人知道一个 gem 或一种方法来做到这一点，这意味着我可以避免尝试编写一个 Yard 扩展来做到这一点，我将非常感激。

【问题讨论】：

标签： ruby documentation yard

【解决方案1】：

经过更多的实验，我发现这很有效：

  # @!method size
  #   @see Array#size
  # @!method <<
  #   @see Array#<<
  # @!method blah
  #   @see Array#blah
  def_delegators :@xs, :size, :<<, :blah # …

很可能有一种方法可以用一两行代码完成此操作，但与编写扩展程序的工作相比，我觉得这非常可接受。

更新：

我刚刚发现这将更好地链接到委托方法的文档：

  # @!method size
  #   @return (see Array#size)

这将从 Array#size 方法中获取已记录的返回值。我希望其他标签也会这样做。它仍然很冗长，但可以接受。

【讨论】：

是的，它看起来不错，但是我的 YARD 没有生成指向原始方法的正确可点击链接。

【解决方案2】：

您需要将这两个概念结合起来。使用@!macro 生成@!method。

以下是我的解决方案版本。但对我来说问题是 OptParser 不包括在内，所以 See 也没有链接。第二个缺点是方法的签名、参数和返回值没有描述。第三个 ick 是字符串 OptParser 是固定的，但确实需要能够调整（参数化）。

如果它转发到项目中包含的方法，那么您可以使用（参见 Foo#method）（在这种情况下没有 @ 符号）并且 Foo#method 中的任何内容都将被复制到新源中。这可以通过在宏内部执行（参见 Foo#$2）来完成——包括括号。见YARD's Reference Tags

# @!macro [attach] def_delegators
#   @!method $2
#     Forwards to $1.
#     @see OptParser#$2
def_delegators :opt_parser, :order!
def_delegators :opt_parser, :on
def_delegators :opt_parser, :on_head
def_delegators :opt_parser, :on_tail
def_delegators :opt_parser, :help
def_delegators :opt_parser, :add_officious
def_delegators :opt_parser, :banner
def_delegators :opt_parser, :banner=
def_delegators :opt_parser, :program_name
def_delegators :opt_parser, :abort
def_delegators :opt_parser, :release
def_delegators :opt_parser, :release=
def_delegators :opt_parser, :version
def_delegators :opt_parser, :version=

【讨论】：

【解决方案3】：

这对我有用。

# @!method do_this
#   @return [mixed] See {Instance#do_this}.
# @!method do_that
#   @return [mixed] See {Instance#do_that}.
delegate *[
  :do_this,
  :do_that,
], to: :instance

其他：

gem yard-delegate 不适用于此类构造。不过它已经很老了。
将 # @!method 放在单个 :method 上方不起作用（被 YARD 忽略）。
更好地指定实际的方法返回值，它会为读者生成一个更舒适的列表。

【讨论】：