From: "Berger, Daniel" <Daniel.Berger@...>
Date: 2009-02-03T00:31:34+09:00
Subject: [ruby-core:21756] Re: New documentation system!

 

> -----Original Message-----
> From: Charles.O.Nutter@sun.com 
> [mailto:Charles.O.Nutter@sun.com] On Behalf Of Charles Oliver Nutter
> Sent: Monday, February 02, 2009 8:08 AM
> To: ruby-core@ruby-lang.org
> 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.

If we're going to go that route, then we should bake it directly into the method declaration:

def some_method(String param1) => Fixnum
   ...
end

Method "some_method" takes a single parameter, that should be a String, and returns a Fixnum. Rdoc could handle this directly. Plus we get metadata from the method declaration itself, instead of trying to parse a comment system. I think there's greater potential for DBC with this approach, too.

No, it's not static typing or, at least, it doesn't have to be. It could be purely advisory. If the type _does_ match, then you optimize. If it doesn't, emit a warning, and you get no optimization.

Regards,

Dan