From: Charles Oliver Nutter <charles.nutter@...>
Date: 2009-02-03T05:51:23+09:00
Subject: [ruby-core:21766] Re: New documentation system!

Austin Ziegler wrote:
> Annotations are one thing; I have no problem with annotations.
> 
> The way that I read it, Daniel was suggesting changing the language so
> that it's *not* just annotation but actively part of the definition of a
> method.
> 
> Again, IME, developers treat signatures with more ... reverence, I guess
> .. than they do annotations.
> 
> It's the signature modification that I'm opposed to, not annotations.

I think we can have both an annotation-aware language and clean 
signatures if we come up with a reasonable doc-based standard...which is 
of course where this thread started :)

I agree the signature modification is undesirable in Ruby's case, though 
I've modified signatures for Duby without too much discomfort:

def fib(i:Fixnum) ...

But Duby supports method overloading and isn't a dynamic language. I 
think doc-based, ignorable, fully API-accessible annotations are the way 
to go for Ruby. YARD looks like at least a pretty good start on that.

- Charlie