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

【问题标题】：YARD: document custom getter/setter pair like attr_accessorYARD：记录自定义 getter/setter 对，例如 attr_accessor
【发布时间】：2011-11-26 20:15:54
【问题描述】：

我正在使用 YARD 来记录我的项目。使用

创建的 YARD 文档属性

attr_accessor :some_attribute

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

def some_other_attribute
  # ...
end

def some_other_attribute= value
  # ...
end

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

【问题讨论】：

标签： ruby documentation yard

【解决方案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 不应该介意，除了在ruby -w 中它会警告方法重定义。如果这让您感到困扰，您也可以在其中添加undef foo, foo=。这有点乱（如果您关心 -w），这就是我们添加 @!parse 和 @!attribute 之类的内容的原因。

【讨论】：

你会在哪里定义@!parse attr_accessor :some_attribute？

【解决方案2】：

你应该可以在类上使用@attr 标签：

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

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

【讨论】：