From: Charles Oliver Nutter <charles.nutter@...>
Date: 2009-02-03T00:08:21+09:00
Subject: [ruby-core:21754] Re: New documentation system!

Luiz Vitor Martinez Cardoso wrote:
> People,
> 
> Thanks for the comments. But now is time to DO! Who is able to get 
> involved? Do this kind of decision needs the approval of MATZ?
> 
> Charles, could you briefly yours plans?
> 
> I'm very decided to help the community improving a new documentation 
> system (or improving YArD)! And now is time to plan.

My plans wrt documentation are pretty slim. Suffice to say I'd like 
something built-in that has a standard API that could double as an 
annotation mechanism, until such time as we gain a real annotation 
mechanism (if ever?)

My hope for annotations, however, is to put some extra power in Rubyists 
hands. For example, Yehuda's example (@param foo<String>) could be 
compiled to assume or enforce that the incoming value is a String, and 
optimize for that case. It would be a simple type-hinting mechanism. 
Other annotations could specify nullability, structured typing (duck 
typing pre-confirmed) and so on. It would open up Ruby to a bit more 
tweakability.

- Charlie