From: Eric Hodel <drbrain@...7.net>
Date: 2010-12-29T06:34:43+09:00
Subject: [ruby-core:33976] Re: Multi-line comments

On Dec 28, 2010, at 13: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

In RDoc ## is only required when the comment does not come before a documentable element but you wish to indicate a method has been created.  For example, methods generated by metaprogramming.  See "Metaprogrammed Methods" and "Hidden methods and attributes" here:

http://rdoc.rubyforge.org/RDoc/Parser/Ruby.html

> -- 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.

RDoc assumes you are documenting everything except in cases where it can't know like metaprogramming.  To opt out of documentation use nodoc or stopdoc/startdoc.