[ruby-core:33975] Re: Multi-line comments

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.

- Loren