From: Hugh Sasse <hgs@...>
Date: 2006-07-18T18:11:06+09:00
Subject: Re: tuplespace - make comments visible to rdoc.

On Tue, 18 Jul 2006, Jan Svitok wrote:

> That 'doesn't add anything' is meant to the last paragraph, as i understood
> it.

Yes: the comment which consists of 

    ##
    # <i>Documentation?</>
    
    class WaitTemplateEntry

has only been changed to

    #
    # <i>Documentation?</>
    
    class WaitTemplateEntry

(i.e, I left a blank line between the comment and the class, see
assumption below) because it is not a comment that adds information
about WaitTemplateEntry.


> This is a cosmetic patch, and the last mentioned comment wasn't worth
> the cosmetics as it is a stub.

I've just tested my assumption that rdoc needs no blank lines between
the comment and the doc, which is why I removed them.  It turns out 
my assumption was false and the existing comments would be picked up
anyway.  They just didn't show up on ruby-doc.org yet, the other reason
I thought I needed to change this.

> 
> That said, it's another question whether it should be committed or not...

I'll be content either way, it depends on the percieved value of stylistic
consitency.
> 
> J.

        Hugh
> 
> On 7/17/06, Eric Hodel <drbrain@segment7.net> wrote:
> > On Jul 17, 2006, at 10:09 AM, Hugh Sasse wrote:
> > 
> > > comments in rdoc conventionally don't start with two # marks and don't
> > > have a blank line before the thing (class, method) they document.
> 
> > > attempts to fix this. Only the comment <I>Documentation?</i> before
> > > WaitTemplateEntry has not been processed this way, as it doesn't add
> > > anything at the moment.
> > 
> > If it doesn't add anything useful I don't see why it should be
> > committed.
> 
>