From: Ken Bloom <kbloom@...>
Date: 2006-10-19T07:55:12+09:00
Subject: Re: Why Class decls and API docs don't Match

On Wed, 18 Oct 2006 15:33:35 -0700, gsm.beamon wrote:

> 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.

That's taken care of in the hook ApplicationController::Layout.included.

> 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 defining a module, the methods defined in the module are included
into the class as instance methods when you use the "include" keyword.
Hwever, the module methods defined with a construction like

module ApplicationController::Layout
  def self.layout
    #foo
  end
end

would not be included as class methods, so we do the next best thing which
is to put all of these class methods into their own module, and put them
in the right place with the hook

module ApplicationController::Layout
   def self.included(other)
     other.extend(ClassMethods)
   end
end

I nevertheless do not know what the rationale is for not bringing
along the class methods of a module along with the instance methods when
the module is included in a class.

--Ken

> 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.

-- 
Ken Bloom. PhD candidate. Linguistic Cognition Laboratory.
Department of Computer Science. Illinois Institute of Technology.
http://www.iit.edu/~kbloom1/
I've added a signing subkey to my GPG key. Please update your keyring.