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:

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


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: