On Mon, 8 Sep 2003 21:58:17 +0900
Tobias Peters <tpeters / invalid.uni-oldenburg.de> wrote:

<snip>
> 
> I'd rather like
>    method_info <<-DOC
>      Create a new MyClass object giving optional defaults
>      for "a" and "b".
> 
>      Category: constructors
>      Parameters:
>        * a: A: The "a" object; defaults to 5
>        * b: B
>    DOC
>    def initialize(a=5,b=B.new) ... end
> 
> I.e. less punctuation, make your "Desc:" tag the default, get method 
> name by overiding method_added

Unfortunately there's nothing tying the method to the method_info
without telling it.  In a few cases, I've used this in subclasses
without any method redefinition, just to make the wordking more
appropriate.  (This is used to generate various forms.)

As for punctuation, I'll make it so you can alter the regexp used for
splitting the documentation... but you may find you need something so
that any description strings that have a ": " in them don't get split.

> Or, maybe
>    doc('Create a new MyClass object giving optional defaults ',
>        'for "a" and "b"',
>        :category, 'constructors',
>        :parameters,
>        :a, 'A: The "a" object; defaults to 5',
>        :b, 'B')
>    def initialize(a=5,b=B.new)

Hah.  The irony... this is similar to the old format I was using.  In
fact, if you prefer this, it'd be trivial to write a function that fills
in the same structure merely using this form.  After using it for
awhile, though, I found it to be much harder to both write (lots of
symbols) and look at (same reason) than something that's mostly text.
Since you write one for _every_ method, it tends to wear.  Also, with
normal strings, you don't have a lot of room for descriptions and the
like, and I ran into this limitation a number of times.

Thanks for the feedback,

-- 
Ryan Pavlik <rpav / mephle.com>

"Another *perfectly* calculated space-time
 splice-n-splice. Now to get back to... wait a second.
 I forgot to carry the TWO!" - 8BT