On 28-12-2010 19:16, Loren Segal wrote:
>
>
> On 12/28/2010 7:12 AM, Rodrigo Rosenfeld Rosas wrote:
>> Regarding documentation, I like the format used by Doxygen and 
>> Javadocs, like using /** */ (or /*! */) and //!. I don't understand 
>> why the same idea was not followed in Ruby, like using '#!' and '/*! 
>> */' besides '=begin/end'.
>
> IIRC this was attempted. I'm not positive, but I believe RDoc has (or 
> used to have) special code for docstrings beginning with "##". That 
> still is a convention used in some documentation, but it's only a 
> stylistic convention. I actually *don't* understand why this is 
> necessary, and honestly, I didn't understand why this was necessary in 
> Java either. If a comment appears immediately before a documentable 
> element, it's probably documentation anyway-- most comments are, in 
> fact, "documentative". IMO it seems a little silly to introduce a new 
> syntax to opt-in to documentation-- we should be opting *out* of 
> documentation (and you can "opt out" by inserting extra whitespace 
> after a comment block in Ruby), because comments are more often than 
> not going to be documentation.

Thank you, Loren. That makes sense and I agree with you. What I really 
wanted is to be able to "opt out" as you say, in some rare situations...

But still, multi-line comments are useful I guess :)

Rodrigo.