Sam Roberts wrote:
> Quoteing jamesUNDERBARb / neurogami.com, on Mon, Nov 08, 2004 at 04:26:26AM +0900:
> 
>>class Foo
>>  attr_reader :bar
>>end
>>f = Foo.new
>>methods = f.methods - Object.methods
>>p methods  # ["bar"]
>>
>>Ruby seems to think I've defined a method.
> 
> 
>>If it's a method, why not document it as a method?
> 
> 
> By this definition, there is no such thing as an attribute, only
> methods.

That is my understanding of Ruby.  I may be wrong.

(I take the view that 'attributes' are a private aspect of an object, 
and that all object access (barring reflection, et al) occurs via 
messages.  I'm one of those who see "@foo" and read it as, "the 
attribute foo."  "attr_reader :foo " creates a method to access this 
attribute, @foo.  I know from prior discussions that this is likely a 
minority view. )

> 
> Ruby has a syntactic short-cut for defining these kinds of methods.

Right.  I see this as a developer convenience for creating methods.  An 
implementation detail, not an expression of intent that should be 
exposed in the API documentation.

> 
> rdoc has a documentation convention of documenting methods defined using
> this short-cut differently from other methods.

This is the issue.  I understand that many, maybe most, like to think of 
Ruby as having almost-but-not-really public instance variables, AKA 
'attributes'.

I understand why some, maybe most, might want to document some methods 
as though they were public instance variables.  I would just prefer that 
this was not baked into the documentation tool.  Or least that there be 
a way to opt out of this using some in-code markup.

As it is, developers who want to use the short form to define attribute 
accessor methods have to accept that the documentation will refer to 
these methods as something other than methods.


James