There was a recent discussion on Scala group list about using students and volunteers (yes, coming from $3M funded company) to work on some less sexy stuff like… missing documentation for the core Scala libraries. You can see full discussion here: http://groups.google.com/group/scala-language/browse_thread/thread/f9144b6771a83dd6
Let me show what I have to deal with almost on the daily basis when working with Scala. This is rather trivial example – but very telling as towards dismal quality of Scala documentation (or practically non-existence of such in many cases).
I was looking at the code like that:
val num = str.toInt
There was an obviously missing error handling (what if
str is not well formatted integer).
So I looked at
StringLike‘s definition of
toInt method. It was empty. Nothing.
OK… I opened the source code for StringLike and saw that
toInt simply delegates to
java.lang.Integer.parseInt(...) method (without a shred of Scaladoc on it):
def toInt: Int = java.lang.Integer.parseInt(toString)
That was enough but I had to double check my memory and I opened Javadoc for
java.lang.Integer.parseInt(...) to see that it indeed throws
NumberFormatException when string cannot be converted to integer.
So, instead of simple glance to Scaladoc, I had to look at Scala’s source code, then to Javadoc to see that method
toInt indeed throws exception (which in Scala a runtime exception and compiler doesn’t even warn me about it).