Hi --

On Thu, 23 Oct 2003, Austin Ziegler wrote:

> On Wed, 22 Oct 2003 10:16:10 +0900, Chad Fowler wrote:
>
> > I didn't feel like RDoc itself was in some way in need of a change.  I
> > was critiquing what I think is non-value-adding documentation such as:
> >
> > # Remove an element from the list
> > def remove_from_list(element)
> > @list.remove(element)
> > end
>
> You're right. If you have the code immediately available, then such
> documentation *is* NVA. In API documentation, though, I disagree that it's
> NVA. I find it quite annoying to open an rdoc API and find that half of the
> methods aren't documented ... until I open the code window and see that it
> really is a simple method.

But if it's a *really* simple method, in the sense that its name says
everything that needs to be known about it, then isn't it essentially
self-documenting, even if it just appears in a list?  I guess I see it
as a kind of cascade: if the method name doesn't suffice, then the
documentation function falls through to the comments.

I just think it's a pity, in a language like Ruby where the code is so
expressive, to clutter up the source files beyond the absolutely
necessary.


David

-- 
David Alan Black
home: dblack / superlink.net
work: blackdav / shu.edu
Web:  http://pirate.shu.edu/~blackdav