From: Jeremy McAnally <jeremymcanally@...>
Date: 2008-02-16T12:37:13+09:00
Subject: Re: RDoc new/initialize discrepency

Right.  Your API documentation should typically document public API
over private, internal implementation details.  Though it does seem
odd that somehow it doesn't signify that the functionality documented
as new is actually initialize.  I don't know if there's really a good
alternative to the current way it's done, though.

--Jeremy

On Fri, Feb 15, 2008 at 7:13 PM, Serg Koren <skoren@comcast.net> wrote:
> >
>
>  Thanks that makes sense.
>
>
>
>  >
>  >
>  >> PS - Anyone have a good explanation of why RDoc translates initialize
>  >> methods as 'new'?   Yes I know you instantiate via:   X.new  but why
>  >> does the method 'initialize'  get documented as method 'new'?   Seems
>  >> a bit confusing for us newbies.
>  >
>  > I assume because initialize only exists to be called on instances
>  > after the 'new' for the class has created them. I have personally
>  > never called #initialize directly; it's always through new.
>  >
>  > I suppose the idea is that by documenting the method that you actually
>  > call, you know how to use the method. (Instead of causing new users to
>  > think that they should write   f = Foo.new; f.initialize( bar, 42 )
>  >
>
>
>



-- 
http://www.jeremymcanally.com/

My books:
Ruby in Practice
http://www.manning.com/mcanally/

My free Ruby e-book
http://www.humblelittlerubybook.com/

My blogs:
http://www.mrneighborly.com/
http://www.rubyinpractice.com/