Effective Javadoc Documentation Illustrated in Familiar Projects

Three years ago, I wrote about practices that I believe lead to more effective Javadoc in my post More Effective Javadoc. In this post, I look at some familiar projects which provide good examples of effective Javadoc documentation practices. I, of course, will only be covering a very tiny representative sample of the many good projects and many good Javadoc ideas that are out there.

1. Advertising Ultimate Demise of Deprecated Method (Guava)

The current version of Guava (Release 10) provides some good examples of more informative statements of deprecation. The next screen snapshot shows the @deprecated text for methods Files.deleteDirectoryContents(File) and Files.deleteRecursively(File). In both methods' cases, the documentation states why the method is deprecated and, most refreshingly, states when it is envisioned that the method will be removed (Release 11 in these cases). I like the idea of stating in the deprecation statement when the deprecated thing is going away. It is easy to learn to ignore @deprecated and @Deprecated if one believes they are really never going to go away. Stating a planned removal version or date implies more urgency in not using deprecated features and provides fair warning to users.

Although the source code for each of these methods employs the @Deprecated annotation, the code from both cases does not specify this text with Javadoc's @deprecated, but instead simply specifies the deprecation details as part of the normal method description text with bold tags around the word "Deprecated." I'm not sure why this was done instead of using the Javadoc tag explicitly intended for this purpose.

2. Documenting Use of an API (Java SE, Java EE, Guava, Joda Time)

When learning how to use a new API, it is helpful when the Javadoc documentation provides examples of using that API. I first learned how to marshal and unmarshal JAXB objects by reading the Javadoc documentation for Marshaller and Unmarshaller respectively. Both of these classes take advantage of class-level documentation to describe how to use the class's APIs.

Guava's class-level description for Stopwatch shows how to use most of that class's features in a concise and easily understandable class usage description.

Use of an API can be documented at the method level as well as at the class level. Examples of this are Guava's Throwables.propagateIfInstanceOf method and the overloaded Throwables.propagateIfPossible methods . The Javadoc documentation for these methods shows "example usage" for each.

API documentation is not limited to the class level or method level. The javax.management package-level documentation provides a nice overview of Java Management Extensions (JMX). The first sentence of the package description (which is what's always shown at top) is simple enough: "Provides the core classes for the Java Management Extensions." However, there are far more details in the rest of the package description. The next screen snapshot shows a small portion of that package documentation.

Another example of a useful package-level description is the package description for Joda Time package org.joda.time. This core package describes many of the concepts applicable to the entire project in one location.

3. Explicitly Declaring Throws Clause for Unchecked Exceptions (Guava)

In my post More Effective Javadoc, I stated that it is best to "document all thrown exceptions" whether they are checked or unchecked. Guava's InetAddresses.forString(String) method's documentation does this, specifying that it throws the runtime exception IllegalArgumentException.

4. Using -linksource (JFreeChart, Guava)

For an open source project, a nice benefit that can be provided to developers using that project is to allow linking of Javadoc documentation to underlying source code. The next screen snapshots indicate this for JFreeChart and Guava. There are two images for each project, with the first image showing the Javadoc with link to source code annotated and the second image showing the source code displayed when the class name is clicked on in the Javadoc.

It is very convenient to be able to move easily between the Javadoc documentation and the source code. Of course, this can also be done in an IDE that supports Javadoc presentation in conjunction with code.

Conclusion

This post has highlighted several familiar projects who Javadoc documentation provides examples of more effective Javadoc-based documentation.