[ruby-core:32623] Standard comment format to provide type information (Was Re: Proposal for Optional Static Typing for Ruby)

Hi All,

I think that the previous discussion was getting slightly off track so I've forked this off to provide an alternative idea I've come up with. In my initial email I said that I believe such type information should not be just put in comments as comments are for documentation. However, while I still believe that to be true, I feel that putting it in comments may be the most pragmatic way. Down the line, if the need is found, the information could be added to the language itself, but I believe comments could be the best way to add this information without really affecting the language.

If we could come to an agreement on a standard format for adding this to documentation comments, then I would be willing to do all the work of updating all of Ruby Core with the the information. In comments the information would be there for tools, but also for users. Doubly so if RDoc was updated to display it in a useful way (which I would also be willing to work on).

Now, there is already a semi-formal comment format for this, but it doesn't cover argument types at all. It does offer information about what is returned, but this can either be the type (with no consistency about how it is written) or the actual possible return values. And of course these comments aren't pervasive, they only seem to be on methods written in C.

A good example is that of the Array class. These are some of the methods listed in the documentation, showing the variety of information

array & other_array

array * int → an_array
array * str → a_string

array << obj → array

array <=> other_array → -1, 0, +1

array == other_array → bool

array.empty? → true or false

array[index] → obj or nil

Now all of this is useful information, but in a consistent, pervasive way it could be even more useful. Does anyone have any thoughts on what the format should be? Or even if this is a good idea?

Thanks

Martin