matz / ruby-lang.org (Yukihiro Matsumoto) writes:

>   (a) multi-line comment for documentation
>   (b) multi-line comment for debugging tool
>   (c) inline comment
> 
> For (a), we already have =begin/=end; for (b), I think we can use
> =begin/=end too.  RDtool does not handle embedded documentation with
> tag other than "RD", so that you can do
... 
> So, I think, we have to discuss about (c) inline comments only.
> What do you think?

OK, this is where I make myself unpopular.

I really, really don't like =begin/=end for anything other than
top-level documentation. If you try to intersperse =begin/=end within
the body of a class, you end up with an indentation nightmare.

I'd very much like to see a full Javadoc-like package for Ruby, but
one that used a subset of Wiki-like formating, and that included a
fairly complete Ruby parser. This would let me write (for example)

  ##
  #  Handle ISO8601 dates. We current accept a subset in the format
  #
  #    CCYY-MM-DDThh:mm:ss+HH:MM
  #    CCYY-MM-DDThh:mm:ssZ
  #

  class Iso8601

    ##
    # Create a new date given an ISO8601 formatted string.
    # Throw: InvalidDateFormat if the string cannot be parsed

    def initialize(date_string)
      # ...
    end


    ##
    # Convert this date to a Ruby <tt>Time</tt> object.
    # Return: aTime

    def to_time()
      # ...
    end
  end


Given the above, I'd expect the tool to be able to do the following:

1. Associate the first comment with the overall class definition.

2. Identify the class, determine it has no explicit superclass.

3. Analyze the class body for attr_xxx and includes

4. Associate the two comment blocks within the class with the
   corresponding methods, and extract the method signatures.

5. Notice that <tt>Time</tt> is a reference to something it knows
   about, and flag it for hyperlinking (and in fact notice any
   references of the form Class::name, Class#name, and Class.name as
   potential hyperlinks)

6. Format the contents of comment blocks using the simple rules of a
   standard Wiki: paragraphs are separated by blank lines, code is
   indented, lists have '*'s or numbers, and so on.

7. Write out a nicely formatted and cross-referenced set of
   documentation that can grow incrementally. Ideally this would
   involve maintaining an intermediate form than can be processed on
   the fly to give me ri-style output, HTML, LaTeX, Postscript, etc,
   etc. For example, if I fed the code above into the documentation
   thingy, I'd then be able to position my cursor on 'to_time()' in my
   Emacs buffer, type C-c C-c C-r, and have it pop up

       ----------------------------------- Iso8601#to_time
         to_time() -> aTime
       ---------------------------------------------------

       Returns this date as a Ruby Time object.

   Where _Time_ was a hyperlink to the Time class's documentation.


The thing I particularly like about this style of documentation is
that it's transparent. The comments aren't littered with all sorts of
punctuation and other markup. If you didn't know that documentation
was being produced, you'd think the code was commented normally. I
also like the fact that the documentation uses a parser to extract
stuff from the source: that means I don't have to type it twice, and
that I don't have to worry about keeping documentation up to date.

I've got much of this working right now, using irb's lexer and
parser. However, I ran into problems getting it to handle method
parameter lists, so I'm waiting for one of the RiR parser teams to
deliver something.

Now none of this requires any change to any existing comment
mechanism. I think that '#'s work just fine. I'm just pointing out
that maybe there are alternatives to =begin/=end for documentation
comments.


Regards


Dave