From: Gavin Kistner <gavin.kistner@...>
Date: 2006-10-19T07:46:29+09:00
Subject: Re: Why Class decls and API docs don't Match

From: gsm.beamon@gmail.com [mailto:gsm.beamon@gmail.com] 
> Anybody who's done any Ruby on Rails will have seen, edited, or
> constructed the following which is suggestive of a general Ruby issue:

[snip]

a) You might want to post this rant/question to the rails mailing list
instead of the Ruby mailing list for more appropriate exposure.

b) Your problem/question seems not to be the fact that the rails
documentation, or the tool that rails uses to generate its
documentation, does not include information you want to see, right?

This is a tricky nut to crack. ActionController::Layout is included in
ActionController::Base in action_controller.rb like this:

ActionController::Base.class_eval do
  include ActionController::Flash
  include ActionController::Filters
  include ActionController::Layout
  include ActionController::Benchmarking
  [...snip...]
end

RDoc currently doesn't see that as an include, I suppose because it
can't figure out where it goes.


More constructively, you might say:
"Hey, I wish RDoc was able to figure out crazy metaprogramming for
proper inheritance"
or
"Hey, I wish someone could modify RDoc so that we could tell it things
to document that it can't figure out for itself"
or
"Hey, I wish someone would fix the rails docs for me...auto-generation
isn't doing it for me."