Why Class decls and API docs don't Match

Discussion in 'Ruby' started by gsm.beamon@gmail.com, Oct 18, 2006.

  1. Guest

    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.
     
    , Oct 18, 2006
    #1
    1. Advertising

  2. Guest

    Partial Resolution?

    > 2. It's in the super class ActionController::Base. No. Check the docs.
    > Read the gem source. There's no layout() in ActionController::Base.


    It's still true: Look at http://api.rubyonrails.com/ and click on the
    class. There's NO LAYOUT().

    But this comment:
    > Read the gem source. There's no layout() in ActionController::Base.

    IS POSSIBLY WRONG. I made my original comments based on the 60 or so
    ..rb files inside
    this directory:


    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.12.5/lib/action_controller

    but if I had looked at this file:


    /usr/local/lib/ruby/gems/1.8/gems/actionpack-1.12.5/lib/action_controller.rb

    I see something approximating a class definition ... but not exactly:

    ActionController::Base.class_eval do
    . . .
    include ActionController::Flash
    include ActionController::Filters
    include ActionController::Layout
    . . .
    end

    But there's still no: include ActionController::Layout::ClassMethods.

    The open nature of Ruby --- the ability to chage module or class
    interfaces in many, many files only makes my original question more
    important:

    HOW DO YOU KNOW, BOTTOM LINE, AFTER ALL THE VARIOUS FILES ARE
    CONSIDERED, WHAT A CLASS DOES?

    I still don't know how ApplicationController::Base can call layout(). I
    still can't understand why it's not in the doc as common sense demands.
     
    , Oct 18, 2006
    #2
    1. Advertising

  3. Ken Bloom Guest

    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.
     
    Ken Bloom, Oct 18, 2006
    #3
  4. Re: Partial Resolution?

    --------------enigBE0710FA17630B1BBD9257F0
    Content-Type: text/plain; charset=ISO-8859-1
    Content-Transfer-Encoding: quoted-printable

    wrote:
    > HOW DO YOU KNOW, BOTTOM LINE, AFTER ALL THE VARIOUS FILES ARE
    > CONSIDERED, WHAT A CLASS DOES?
    >=20


    Crystal balls help. I feel the pain. Sadly enough, irb, listing methods
    of an object interactively, and then wading through docs to guess where
    they are defined are your only salvation. Basically, hope you never have
    to use more of libraries like this than you can keep in your head after
    learning them, or that someone does Cruel and Unusual things to rdoc to
    let it figure out these shenanigans.

    David Vallner


    --------------enigBE0710FA17630B1BBD9257F0
    Content-Type: application/pgp-signature; name="signature.asc"
    Content-Description: OpenPGP digital signature
    Content-Disposition: attachment; filename="signature.asc"

    -----BEGIN PGP SIGNATURE-----
    Version: GnuPG v1.4.5 (MingW32)

    iD8DBQFFNrfky6MhrS8astoRAmN+AJ4tOW7SHM5uVKvkgfEOpGYZzD0y9QCeP49N
    S9ZooLKM7bFp1xEjBi/mHRk=
    =vUat
    -----END PGP SIGNATURE-----

    --------------enigBE0710FA17630B1BBD9257F0--
     
    David Vallner, Oct 19, 2006
    #4
  5. Guest

    Re: Partial Resolution?

    > Crystal balls help. I feel the pain. Sadly enough, irb, listing methods
    > of an object interactively, and then wading through docs to guess where
    > they are defined are your only salvation. Basically, hope you never have
    > to use more of libraries like this than you can keep in your head after
    > learning them, or that someone does Cruel and Unusual things to rdoc to
    > let it figure out these shenanigans.
    >

    Thank you.

    Ruby Community: why doesn't RDOC tell you all the includes or requires?
    I mean if ApplicationController::Base said that it included files
    <....> then I could have put two
    and two together.

    My only problem --- which I belatedly solved and which was immediately
    pointed out
    by another poster --- is that I was looking in the wrong files. Had I
    kept on looking I
    would have found even more files that evenutally defined the class and
    included
    ApplicationController::Layout which presumbably includes
    ApplicationController::Layout::
    ClassMethods. And volia there's layout().

    The connection is important. This seems obvious to me. But other
    posters have
    said, "Hey, I found it not problem in .../layout.rb. So what's the
    deal?" The deal is
    that this:

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

    Why is should anybody jump and then why is it correct to jump from
    ActionController::Base to ActionController::Layout::ClassMethods per
    ..../layout.rb?
    That isn't answered by merely pointing .../layout.rb.
     
    , Oct 19, 2006
    #5
  6. Phrogz Guest

    Re: Partial Resolution?

    wrote:
    > Ruby Community: why doesn't RDOC tell you all the includes or requires?
    > I mean if ApplicationController::Base said that it included files
    > <....> then I could have put two
    > and two together.


    It does, most of the time.
    Just not when the code in question uses various 'tricky' techniques to
    do so.
     
    Phrogz, Oct 19, 2006
    #6
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Prashanth

    newbie: C decls Vs. C++ decls.

    Prashanth, Dec 13, 2003, in forum: C++
    Replies:
    5
    Views:
    415
    Jerry Coffin
    Dec 20, 2003
  2. Mr. SweatyFinger
    Replies:
    2
    Views:
    2,077
    Smokey Grindel
    Dec 2, 2006
  3. KYG
    Replies:
    2
    Views:
    929
    Ian Collins
    Aug 18, 2008
  4. Stéphane Wirtel
    Replies:
    0
    Views:
    200
    Stéphane Wirtel
    Apr 19, 2007
  5. Al
    Replies:
    1
    Views:
    162
    Henry Law
    Oct 16, 2005
Loading...

Share This Page