在 Rails 中添加模型范围的文档答案

【问题标题】：Adding documentation for model scopes in rails在 Rails 中添加模型范围的文档
【发布时间】：2011-11-08 14:07:12
【问题描述】：

我不确定这是否真的可行，但我正在尝试通过在 app/models 文件中添加范围文档来使我们的 rails 应用程序的文档更加完整。我正在尝试做的是：

# This is a description of what the scope does and the action that it performs
scope :newest_records, order("created_at desc").limit(50)

然后，当我在应用程序上运行 rdoc 时，我希望看到 newest_records 被列为公共类方法以及更传统的方法，这些方法将被记录为：

# some more documentation about this method
def self.a_class method
  ....
end

编辑

我意识到这个问题可能有点模棱两可。所以这里试图澄清一下：目前，当我尝试在scope 声明上方添加注释行时，我没有得到 RDoc 为范围生成的文档。我知道 RDoc 可以获取元方法/属性，否则它不会在用attr_accessor 声明的文档中显示属性。所以我的问题是如何将 cmets 添加到我的文件中，以便：

该方法出现在我的 RDoc 生成文档中
它显示为公共类方法（与公共实例方法等相反）

【问题讨论】：

究竟是什么问题，是“无法添加文档...”还是“添加文档时出错...”等等。我只是不确定。尝试时评论当前不显示吗？ rdoc 显示了吗？很乐意提供帮助，只是不确定问题是什么。
@Michael Durrant - 好点。在第二次阅读时，我的问题措辞不是很好。将编辑以使其更清晰。

标签： ruby-on-rails ruby-on-rails-3 rdoc scopes

【解决方案1】：

在 RDoc Docs 中进行了一些挖掘之后，我想我已经设法回答了我自己的问题。

您可以按如下方式记录范围：

##
# :singleton-method:
# Documentation for the scope to explain what it does
scope :newest_records, order("created_at desc").limit(50)

双重哈希用于提取元编程方法，如果您正在创建实例方法，那么您只需要这样。但是，作为作用域创建一个类方法，您还需要使用 :singleton-method: 行来表明这一点。文档在以下几行中继续正常进行。

您可以在RDoc Documentation 中查看记录元方法等的完整语法

【讨论】：

【解决方案2】：

作用域是类方法，所以 Rdoc 做得对。据 Rdoc 所知，我会说这是有效的。

使用 YARD 等更可扩展的东西，您可能会有更好的控制。

【讨论】：

感谢罗伯特的建议。看过 YARD 生成的文档——它们看起来很不错，所以将来可能会考虑使用它