Javadoc Rant

Javadoc is this wonderful invention. It allows a programmer put a comment into their code above the methods they are writing in order to generate automatic API documentation. But it’s simplicity is also a curse often times Javadoc descriptions are absolutely awful.

And in some cases Javadoc descriptions which are suppose to contain how and why you would use something serve to only remind a programmer what the method name was called. For example in the GXT API for google web toolkit extra widgets we have this excerpt:

 

getStyle

public TreeStyle getStyle()

Returns the tree style.

Returns:

the tree style

 

Hmm… I think most programmers can guess the that from reading the method. But what is a style? In particular what is a TreeStyle? What does it define?

Almost all JavaDocs I’ve come across so far suffer from lack of information. If any JavaDoc users out there are listening. The reason many programmers flock to languages like C# is the documentation is gold. Javadoc is a great technology but if it is to compete Javadoc writers need to not only state what the method does but also mention why you may want to use it.

In addition almost every MSDN documentation I’ve seen to date gives at least one example of the method in practical use so the programmer has no doubt as to how to use that API. Ask yourself when’s the last time you saw a useful example inside a Javadoc?

Technology is great Javadoc is incredibly easy to generate, but the ease of use leads to very poor documentation. Most JavaDocs are an afterthought and it’s highly disappointing.