YARD：记录自定义 getter/setter 对，如 attr_accessor

Question

我正在使用 YARD 来记录我的项目。 创建的 YARD 文档属性

attr_accessor :some_attribute

在单独的“实例属性摘要”部分中 。现在我有另一个属性，但是使用自定义 setter 和 getter，

def some_other_attribute
  # ...
end

def some_other_attribute= value
  # ...
end

所以基本上我的问题是，如何让 YARD 记录这对 setter/getter，就像前一种情况中的 attr_accessor 一样，并列出 “实例属性摘要”中的“some_other_attribute”？

Answer 1

从 0.8 开始（目前处于预发行版），@!attribute 指令是表示对象是属性的推荐方法。已弃用 @attr_* 标签，取而代之的是该指令。您还可以（在 0.8.0+ 中）：

# @!parse attr_accessor :some_attribute

解析不一定由 Ruby 执行的代码。在 0.8 之前，您可以直接添加 attr_accessor，然后重新定义 setter/getter，如下所示：

class MyClass
  attr_accessor :foo
  def foo; something_else end
  def foo=(v) something_else(v) end
end

Ruby 不应该介意，除了在 r​​uby​​ -w 中它会警告方法重新定义。如果这让您感到困扰，您也可以在其中添加 undef foo, foo= 。它有点混乱（如果你关心 -w），这就是为什么我们添加了诸如 @!parse 和 @!attribute 之类的东西。

Answer 2

您应该能够在类上使用 @attr 标记：

# @attr [String] name The name of this object. 
class MyClass
  def name
  end
  def name=
  end
end

还有其他标记（例如 @attr_reader 和 @attr_writer）也很有帮助。