Javadoc

From APIDesign

Javadoc is one of the best inventions of Java. When we were working on the Xelfi student project (which later evolved to NetBeans), we needed not just a working IDE, but also some documentation. Java was the first language that allowed one to generate documentation from the code. So we did it - we generated hundred of pages of Javadoc. Most of the methods had no comments, but as the Javadoc tool wasn't widely known at that time, everybody was impressed and we passed the final Xelfi project exams.

Not Every Package Deserves Javadoc

As generating Javadoc is so easy in Java, many projects generate it for all their classes (just like we did in case of Xelfi). However, that is wrong. Not every package, not every class in your project is intended as an API - there are often some implementation packages. Those should be left out from the Javadoc.

Classes aren't Entry Points

By default Javadoc doesn't provide an overview and many project leave it as such. That is wrong, the last thing user of an API want is to look at tens or hundreds of classes and trying to guess which one is the most important one.

Always write an overview and include usecases in it. Only then navigate user to the actual Javadoc of your methods.

Code Samples

Each Javadoc should be spiced with code samples. However, often the code samples are out of date, or incorrect. That is indeed bad.

To generate always correct, colorized code snippets, use Codesnippet Javadoc Doclet.