Scala Documentation Rant…

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).

Nice.