From: gsm.beamon@...
Date: 2006-10-19T07:35:11+09:00
Subject: Why Class decls and API docs don't Match

Anybody who's done any Ruby on Rails will have seen, edited, or
constructed the following which is suggestive of a general Ruby issue:

class ApplicationController < ActionController::Base
    layout "standard"
end

Now nevermind that to a JAVA/Eiffel/C/C++ programmer the naked method
call to layout() should be illegal because it's not inside a function
block. I can get over that.

Just ask yourself this: Where is layout() defined?

1. It's in ApplicationController? No. What you see *IS* the complete
definition. No layout() there.
2. It's in the super class ActionController::Base. No. Check the docs.
Read the gem source. There's no layout() in ActionController::Base.

So where is it?

Get this: it's in ApplicationController::Layout::ClassMethods. But
ApplicationController, Layout, ClassMethods are all modules. And while
Base is a class inside ApplicationController I don't see where it
includes ApplicationController::Layout::ClassMethods.

Bottom line: how is layout() in scope for ApplicationController? And,
as appears to the case, if layout is callable from any
ActionController::Base heir, why in the heck isn't it in the docs for
ActionController::Base?

When I go and read the docs for ActionController::Base, I want to know
*ALL* the stuff it can do. That is is just plain common sense to in
most any other OO language. Ruby appears to buck this norm.