Tag Archive

If you take a look at the Rails source code, you’ll find numerous useful comments like this one from ActionController::Base:

# All requests are considered local by default, so everyone
# will be exposed to detailed debugging screens on errors.
# When the application is ready to go public, this should be set to
# false, and the protected method <tt>local_request?</tt>
# should instead be implemented in the controller to determine
# when debugging screens should be shown.
@@consider_all_requests_local = true
cattr_accessor :consider_all_requests_local

But if you check your favorite Rails API site for documentation of consider_all_requests_local, you’ll come up blank. What’s up?

I spent some time chasing this, and it turns out to be a conflict between the way that Rails is commented and the way that rdoc thinks things should be done. There’s actually a ticket in the old Rails Trac with a proposed resolution for this. As it happens, that ticket isn’t quite right, but it provoked rdoc into changing things. The secret lies in the rdoc 2.x support for documenting metaprogrammed methods.

To properly document cattr_accessor (and similar) declarations in your own Rails code, you need to do two things. First, upgrade from your musty old rdoc 1.0.1 to a more recent version - 2.2.1 is current. If you look at their downloads you will find there is a gem version, but just installing this may not be enough: putting the gem on my system gave me rdoc 2 from the command line but rdoc 1 from rake tasks. That’s because (at least on my Mac), rdoc is also out there in the ruby/1.8 standard tree, and so I had to replace the 1.0.1 there with the new bits.

Second, you need to change your markup comments to tell rdoc that this is a metaprogrammed method. Here’s the revision for that method from ActiveController::Base:

@@consider_all_requests_local = true
##
# :singleton-method:
# All requests are considered local by default, so everyone
# will be exposed to detailed debugging screens on errors.
# When the application is ready to go public, this should be set to
# false, and the protected method <tt>local_request?</tt>
# should instead be implemented in the controller to determine
# when debugging screens should be shown.
cattr_accessor :consider_all_requests_local

The ## indicator tells rdoc that this is a metaprogrammed method, which means it will ignore the first token on the declaration and pick up the second one as the method name. The # :singleton-method# indicator tells rdoc to document this as a class method rather than as an instance method.

The Rails Documentation team is exploring how we’ll fix up the core Rails source to use the new markers. Meanwhile, you should start using this anywhere that you have the cattr methods in your own code or plugins - and upgrade your rdoc bits in anticipation.