Developer

The importance of the humble Javadoc

Often underappreciated, Javadoc and the generation of API specifications play a vital role in the development of Java apps. Often API specifications are the only documentation available, so don't neglect them.


Quick—think of three things you find really cool about Java.

So what did you think of—OS independence, Java's object-oriented nature, and freedom from pointers? In all probability, Javadoc did not figure into your list. Even if you had listed the top 10 features of Java, I doubt Javadoc would have been a part of it.

That is the nature of Javadoc. We use it everyday, we can't think of developing software without it, yet we don't rank it as important. The HTML files generated by the Javadoc tool are technically known as the API specifications, but the files are mostly referred to as the Javadoc for a certain API.

First encounter
On my first encounter with Javadoc, I was very impressed by how quickly and easily it could create HTML documentation. Much of the credit for Java's growth can be attributed to Javadoc, because it takes a lot less time for developers to learn new APIs if they have good API specifications on hand. So even though new APIs keep coming, Java developers can manage to learn all that is relevant and stay afloat.

Open source software is a prime example of great Javadoc usage. Considering the voluntary nature of contributions to open source software, it's not surprising that we do not always find good documentation and user guides. However, because Javadoc uses Java code to generate the API specifications, the software at least has a comprehensive API specification to bank on. This is often all the documentation that exists and yet it is good enough, because Javadoc is very capable of exploiting the features of HTML to generate useful documentation.

Having a proper API specification on hand just before you start coding can be very useful. Make it a point to input as much Javadoc information as possible when you create your UML class diagrams. Most UML tools are quite capable of taking Javadoc comments as input and then generating the API specifications.

Observations
Here are a few observations about Javadoc and the simple things that are often misused or overlooked in creating API specifications:
  • Don't forget to write the package level Javadoc in a file named package.html. This file should be placed into the directory where the code files for that package exist. Javadoc is capable of picking up that file and using its contents.
  • Using the same old white and blue color combination for all your API specifications is a remarkably boring way to go about it. Why not tweak the stylesheet.css file located at the root of the HTML files. Minor changes can get you an API specification that is fresh and easily distinguishable. You also have the option of using your own style sheet by using the -stylesheetfile command line option in the Javadoc command.
  • For the method return tag, write an explanation of what is being returned, not the class name. Unlike the param tag, where you need to specify the name of the parameter, you don't need to do this for the return tag because only a single value can be returned by a method. So the method signature reveals the class being returned. Also, don't use the return tag for methods returning void.
  • Use the see and link tags to provide cross-references. These can be especially useful if the API specification is the only documentation for your piece of code.

Doclets
What do you do if you wish to generate Javadoc in a different format or do something beyond the default Javadoc features available? You either write your own doclet or find one written by somebody else. Doclets are Java programs written using the Doclet API and are used by Javadoc to generate output in the form specified by the doclet. By default, Javadoc uses the standard doclet. In most cases, you'll find features of the standard doclet to be sufficient, so it is unlikely that you would have to write your own.

To use any doclet other than the standard one, you have to use the -doclet command line option to the Javadoc command.

For more information
Check out Doclet.com for more information and the various doclet-related tools that are available.

XDoclet
One tool that is rapidly growing in popularity and that I found particularly impressive is XDoclet. XDoclet is a code generator that uses Javadoc-like tags to get the requisite information and generate the appropriate files. It can be especially useful if you're annoyed by the multiple file maintenance requirements of EJBs.

The Home Interface, Local Interface, Remote Interface, the deployment descriptors, and descriptors specific to various application servers are some of the files that you have to create to get even a basic EJB working. With XDoclet, all you have to do is write the core bean class and use the XDoclet tags to write Javadoc-like comments for the class and each method. Based on the tags you've used, XDoclet can quickly generate the various files. XDoclet tags are written in the normal Javadoc comment style and can coexist with your existing Javadoc comments.

XDoclet is triggered from Ant tasks so it would involve only a few changes to your Ant build script to have XDoclet generate code for you. Once this code is generated, the script can proceed to routine Ant tasks. The XDoclet homepage lists everything that will make selling the XDoclet idea to your boss a lot easier. XDoclet already provides tags for a variety of popular tools, and although XDoclet's ability to simplify EJBs is what attracted me to it, it certainly is capable of a lot more.

Well served
Javadoc has served Java very well and has been a great asset to Java developers worldwide. They say, "There is none worse than a lover scorned," and you can add to that "and a developer who has to understand and maintain uncommented code." Be good to fellow Java developers and write proper Javadoc comments.

Editor's Picks