From: Gavin Sinclair <gsinclair@...>
Date: 2004-03-05T09:49:12+09:00
Subject: Re: Comment football being played... with lib/test/unit.rb

On Friday, March 5, 2004, 3:29:06 AM, Dave wrote:


> On Mar 4, 2004, at 10:06, Nathaniel Talbott wrote:

>> Dave and Gavin, you should probably have a conversation about where
>> the comment should be, and why, since you keep going in and undoing
>> each others change. I'm guessing the issue is that for ri it's better
>> to have a class-level comment, and for generated html it's better to
>> have a file-level comment, and I'm curious to hear what the final 
>> consensus is.

> Oops - I missed the original change here.

> I vote for it the way it is now, with the possible addition of a 
> file-level comment with a pointer to the class-level comment. That way
> both HTML and the ri will produce reasonable results. The idea is to
> make

>     ri Test::Unit

> produce meaningful results (and right now it produces really nice 
> looking results: nice job Nathaniel/Gavin)

> ri doesn't look at file level comments (because it didn't seem 
> particularly meaningful), so as unit.rb was previously, all that 
> wonderful comment was being lost.


I agree.  My general philosophy is to put all the documentation at the
class level (so long as it's relelvant), and just put credits and a
one-line intro at the file level (for HTML generation putposes).

So there may be one more (small) change coming up :)  There's a
slight, and probably unimportant, formatting glitch in the comments at
the moment as well.

And I can't take credit for the quality that's there at the moment;
Nathaniel has had it there for ages!

Cheers,
Gavin