search

mojombo / tomdoc

A flexible code documentation specification with human readers in mind.
333 stars 47 forks source link

don't focus on classes as types #3

Closed joshsusser closed 14 years ago

joshsusser commented 14 years ago

In The Arguments Section the spec states "When you specify a type, use the proper classname of the type", and that is echoed throughout the spec. But in Ruby and other duck-typed languages, the class is often not the type that you care about most. And I'm assuming that modules are pretty much equivalent to classes for typing. But there are also types without formal names, such as booleans. How do you specify the type of a boolean? "TrueClass or FalseClass"? That's quite the common exception for your required way to specify types. You don't actually use the magic word MUST, but you don't say SHOULD either.

Besides being sometimes hard to describe, the class-as-type type of an arg or return value is often not very interesting. What about types like positive numbers, sorted lists, arrays of arrays, or frozen objects? Ruby isn't a statically typed language, and having a doc standard for it be limited to classes as types doesn't seem very useful.

weppos commented 14 years ago

+1 for the nil, true and false question.

defunkt commented 14 years ago

You're right that Ruby is a duck-typed language, and TomDoc takes advantage of this: if a String argument is expected, you can hand the method anything that quacks like a String and everyone should be fine.

This isn't a type system. It's documentation. If you want to be more generic, accept an Object and explain the methods it should respond to.

As for the "hard to describe" types: Returns a positive Integer. Returns a Boolean. Returns nil. Returns an Array of Strings.

mojombo commented 14 years ago

Yeah, the beauty of TomDoc is that if you have special things going on, just explain them, like Chris said. If you really want to drive home a duck-typed situation, then you can say An Object that has a to_a method that returns an Array or the like. As long as users understand what is expected, that's the key. I can revise the wording to make this a bit more clear.

joshsusser commented 14 years ago

Well to be pedantic, there is no Boolean class or module in Ruby. And in Ruby it might actually be important to distinguish between a return value that is strictly false or true, as opposed to one that is false/nil vs any true-ish value. You see a lot of #is_predicate? methods in Ruby, and it's often hard to tell what the return type is. I don't think this is a "special thing", but a very common use case, and it would be nice to see an easily understandable convention for documentation for it.