From: Gavin Sinclair <gsinclair@...>
Date: 2004-11-08T14:00:22+09:00
Subject: Re: [RDOC] Documenting accessor methods as methods

On Monday, November 8, 2004, 12:19:13 PM, Dave wrote:


> On Nov 7, 2004, at 17:37, James Britt wrote:
>> 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.

> That's where we differ, and why RDoc distinguishes between attr and 
> regular method definitions. It isn't just a macro facility: it's an 
> expression of intent.

I agree with this; I like (on balance) seeing attributes documented
separately; and I would like to see an :attr: directive introduced.

But there's one problem as I see it at the moment: attributes don't
appear in the method pane.  This sometimes incurs difficulties: try to
find a method (you don't know what class) in a large body of
documentation, only to discover it's an attribute.

Gavin