'. '


From APIDesign

Jump to: navigation, search

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.

[edit] 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.

[edit] 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.

[edit] Code Samples

Each Javadoc should be spiced with code samples. However, often the code samples are out of date, incorrect and hard to read. That is indeed bad. Just compare the ugly old state:


The old code is written with the same monospaced font which doesn't make a difference between Java keyword, class identifier, etc. However, there is a simple way to improve your Javadoc: To generate always correct, colorized code snippets, use Codesnippet Javadoc Doclet. Here is the previous sample rewritten to extract code snippets from the test code:


The code samples are longer, keywords are represented in bold, references to known API classes are hyperlinked (so one can jump directly to their definition). Obviously the whole sample is absolutely correct as it has to compile when building and executing the tests.

Personal tools