From: Joel VanderWerf <vjoel@...>
Date: 2009-02-26T02:32:23+09:00
Subject: Re: [ANN] rdoc 2.4.0 Released

Eric Hodel wrote:
> On Feb 25, 2009, at 00:04, Joel VanderWerf wrote:
>> Can the :method: directive emulate attr_reader, and really make the 
>> output doc look the same as if attr_reader had been used instead of 
>> some other class method? Is there a way to display "[R]", and group it 
>> with other attrs?
> 
> No.
> 
> I'm very strongly considering merging the attr-defined methods with 
> regular methods.  Present your counter-argument here.

Treating attrs the same as other methods does make sense in light of the 
uniform access principle, but practically speaking it seems a bit 
severe. Libraries like fxruby use the attribute section extensively, and 
it is useful because the methods that appear there not only have more of 
the attr-nature, but also are based on C++ public data members. It's a 
helpful bridge back to the Fox world. Plus, it gives you a way to scan 
the rdocs to see (i) what dials and switches can be adjusted on an 
object ([W] and [RW]), and (ii) what constitutes the visible state of 
the object ([R] and [RW]).

I guess :section: is a solution to this, but it will mean some work for 
library maintainers, and :section: is not widely used. I have 221 gems 
installed, and :section: appears only in rdoc, rubygems-update, and one 
file in merb. I do use :section: extensively in my own rdocs. How long 
will it take for all of the doc maintainers to respond to this change?

-- 
       vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407