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

发布于 2024-12-02 09:47:27 字数 753 浏览 10 评论 0原文

我不确定这是否真的可行，但我试图通过在 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 声明的文档中显示属性。所以我的问题是如何向我的文件添加注释，以便：

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

原文

I'm not sure if this is actually possible or not but I'm trying to make the documentation of our rails app more complete by adding documentation for the scopes in our app/models files. What I'm looking to try and do is:

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

And then when I run rdoc over the app I want to see newest_records listed as a public class method along with the more traditional methods which will get documented like:

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

EDIT

I realise this question may be a bit ambiguous. So here's an attempt to clarify: At present when I try to add a comment line above a scope declaration I get NO documentation generated by RDoc for the scope. I know RDoc can pick up meta methods/attributes otherwise it wouldn't be displaying attributes in the docs which are declared with attr_accessor. So my question is how do I add comments to my file so that :

The method appears in my RDoc generated documentation
It appears as a public class method (as opposed to public instance method etc)

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

弱骨蛰伏 2024-12-09 09:47:27

经过一番研究 RDoc 文档后，我想我已经成功回答了我自己的问题。

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

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

双散列用于选取元编程方法，如果您要创建实例方法，那么这就是您所需要的。然而，当作用域创建一个类方法时，您还需要使用 :singleton-method: 行来表明这一点。文档在以下几行中继续正常进行。

您可以在 RDoc 文档<中查看记录元方法等的完整语法/a>

After some digging around in the RDoc Docs I think I've managed to answer my own question.

You can document a scope as follows:

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

The double hash is used to pick up meta-programmed methods, and if you're creating an instance method then that's all you need. However as scope create a class method you also need to use the :singleton-method: line to indicate that. Documentation the continues as normal on the following lines.

You can see the full syntax for documenting meta-methods etc in the RDoc Documentation

回复收藏 0 原文