From: James Britt <jamesUNDERBARb@...>
Date: 2004-11-08T13:20:46+09:00
Subject: Re: [RDOC] Documenting accessor methods as methods

Dave Thomas wrote:
> 
> On Nov 7, 2004, at 13:26, James Britt wrote:
> 
>> > If it's a method, why not make it a method?
>>
>> 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.
> 
> 
> James:
> 
> I probably wrote the book that gave you you this information: I really 
> don't need you telling me back :)

Yes: and no doubt that's true.  You also know I reviewed that part of 
the book, and know what I think, so the round-about suggestion of 
writing out methods was equally unnecessary.  Perhaps you meant well, 
but it struck me as condescending.

Anyway, I gather that rdoc will not do what I want.

> 
> If the distinction between attributes and methods is significant to you, 
> then you are losing clarity in your code by using attributes when you 
> want them documented as methods. That is, you want the users of your 
> documentation to think of these things as methods, but you don't care 
> that readers of the code will see them as attributes. That feels sloppy 
> to me, and that's why I asked why you wouldn't want to type them in as 
> methods.

Well, that's the disconnect, and as you've noted elsewhere, we've had 
this discussion before, and neither has found the other convincing.  I 
know your position on this, I know this is built into rdoc, I think I 
understand the motivation.  I just don't share that view of attribute 
accessor methods.

I simply wanted to know how I can get these methods documented as 
methods, rather than as something else, while using the short-hand 
notation.  If rdoc doesn't offer this choice, then simply saying so 
would have sufficed.

I want users of the code to think of method as methods.  Readers of the 
code are going to think what they want.  It may very well be that they 
view certain methods as something other than methods, but writing out 
the method long-hand, when all it does is read or write to something 
that begins with the 'at' symbol, is not going to mean much to someone 
who views Ruby's object model differently than I do.  I disagree that 
using attr_* means anything other than that I'm too lazy to type.

I gather there is enough cultural momentum that this notion of public 
properties (a la Java, perhaps) is the norm.  I think this complicates 
thinking about Ruby, but that's my problem.

I just wanted to know if something was possible.  Although no one has 
yet to say so, I suspect that it isn't.


Thanks,


James