Adding documentation for model scopes in rails

Question

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)

Catastrophe

what exactly is the question, is it 'unable to Add docu...' or 'error adding docu...' etc. I am just not sure. Does the comment not show up currently when tried? Does rdoc show it? Happy to help, just not sure exactly what the question is. – Vassily

@Michael Durrant - Good point. On 2nd reading my question isn't very well worded. Will edit to make clearer. – Catastrophe

Answer 1

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

Catastrophe

Answer 2

Scopes are class methods, so Rdoc is doing it right. I would say that's working as far as Rdoc knows.

You might have better control using something more extendable like YARD.

Passementerie

Thanks for the suggestion Robert. Have seen YARD generated docs - they look pretty nice so may well look at using it in the future – Catastrophe