From: Harry Ohlsen <harryo@...>
Date: 2001-12-12T08:03:49+09:00
Subject: [ruby-talk:28288] Re: rdefs : a puny doc tool

In article <20011211174325.C6125@atdesk.com>, "Paul Brannan"
<paul@atdesk.com> wrote:

> I like the first one better, since it lets me do this:
> 
>   # class| Class Foo is a very useful class.  I like to use it a lot. 
>   It # class| does very cool and interesting things, and it makes me
>   very # class| happy.
>   class Foo
>     # def| The initialize method is used to initialize a Foo object.  It
>     # def| is a very fun and exciting method to call.  It can take any #
>     def| number of arguments.
>     def initialize(*args)
>       # do something
>     end
> 
>     # def| The foo method is also very fun, but not very interesting. 
>     It # def| is a very boring method, and does not play well with
>     others. def foo
>       return nil
>     end
>   end

Yes, but if you want to write that level of documentation, surely you'd
be better off using RD?  I think the idea behind this was just to get a
quick summar, not to be an all-singing, all-dancing documentation tool.

Putting all those "def|" and "class|" in there would make the code look
a bit messy (IMHO) ... and it's error prone; you've got a place in every
line of documentation where you could make a typo.