Quoteing dave / pragprog.com, on Mon, Nov 08, 2004 at 02:47:37AM +0900:
> 
> On Nov 7, 2004, at 8:05, James Britt wrote:
> 
> >And how can someone get
> > attr_reader :foo
> >
> >to appear with the method definitions?
> 
> Make it a method?   :)
> 
> It seems to be that if you're trying to save typing by entering
> 
>     attr_reader :foo
> 
> rather than
> 
>    def foo; @foo; end
> 
> you're giving up a fair amount of clarity in your source to save 3 
> characters. If it's a method, why not make it a method?

I agree with this, but the opposite is useful, and not possible to get
by changing the code.

What goes in the attrs section is decided by an implementation detail of
using attr_*, but if you have 3 "attributes", but 1 you have to
implement with some code (maybe it returns an object/information you
don't to want to create/calculate until necessary), it'll appear in the
methods section. Fair enough, but a reader doesn't care how I implement
my attributes, and having whats in the section be so arbitrary makes it
hard to find things, you never know what section it will be in when
consulting the docs.


Anyhow, I find it really useful to distinguish between attributes and
methods in documentation, even though its not a technical distinction,
its more of an "intention" distinction.


But... having the distinction decided only by an implementation detail
is a little frustrating, any chance of adding an :attr: attribute syntax
to docs, so that you can force a method into the attribute section?


Also, what about arbitrary sections!  So you could decorate a method
with :section-Conversion Methods:, and it would go in a seperate section
from the other methods called Conversion Methods.


I love rdoc, but I could love it more...

Thanks!
Sam