From: Loren Segal <lsegal@...>
Date: 2010-12-29T07:54:48+09:00
Subject: [ruby-core:33981] Re: Multi-line comments



On 12/28/2010 5:37 PM, Ryan Davis wrote:
> On Dec 28, 2010, at 13:16 , Loren Segal wrote:
>
>> I believe RDoc has (or used to have) special code for docstrings beginning with "##". [...]  I actually *don't* understand why this is necessary
> The only place this is required in my code is in front of non-methods like attr*s or define_methods. Otherwise I have no idea why you're positing that the "##" is "necessary" as it obviously isn't.

I never said it was necessary in RDoc, I was questioning why it was 
necessary in general.

>> and you can "opt out" by inserting extra whitespace after a comment block in Ruby
> huh? you can?
>
In YARD, yes. I would consider the behaviour to be unreasonable if a 
tool generated documentation for the following gist with so much 
whitespace: https://gist.github.com/757859

I hadn't actually tested this in RDoc until now. I figured it did the 
sane thing and stopped following a comment after enough whitespace. I 
was actually surprised to find out that it does not, so I guess you 
can't in RDoc, but you can in YARD.

YARD actually waits for 2 lines of whitespace to stop following a 
comment, so your code still actually documents fine in both tools. Any 
more empty lines and it would not, though.

- Loren