From: jweirich@...
Date: 2001-07-06T14:26:23+09:00
Subject: [ruby-talk:17380] Re: RubyDoc.  was /* */ comments

>>>>> "Dave" == Dave Thomas <Dave@PragmaticProgrammer.com> writes:

    Dave> OK, this is where I make myself unpopular.

Actually, I agree whole-heartedly.  I like this idea.

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

    Dave>   def to_time()
    Dave>     # ...
    Dave>   end

I'd also like to see short, one-liner comments supported.  For example ...

    ## Advance to the next lexical token.
    def advance
      # body
    end

    Dave> 5. Notice that <tt>Time</tt> is a reference to something it knows
    Dave> about, and flag it for hyperlinking

Eiffel uses the convention that `var' in a comment references a
program entity named "var", and will format "var" in a different font
(or color) in its short format.  (Eiffel short format is similar to
Javadoc output).

-- 
-- Jim Weirich     jweirich@one.net    http://w3.one.net/~jweirich
---------------------------------------------------------------------
"Beware of bugs in the above code; I have only proved it correct, 
not tried it." -- Donald Knuth (in a memo to Peter van Emde Boas)