The “Break it Down” Blog

Writing good Javadoc is hard enough as it is; getting the descriptions just right, explaining enough of the API to make it clear without imposing implementation guidelines on implementors, etc.

One thing I’ve been doing for the last few years to make my Javadoc actually look better is trying to be better about using <code></code> tags to wrap keywords, classes and method names in my documentation to clearly accentuate what I’m writing about. Two issues with this is:

1. It is time consuming to type so many extra <code></code> blocks in your Javadoc while you are working.
2. It doesn’t offer any functional additions to your Javadoc, just visual (assuming the reader even notices the shift in rendering)

While reading through the Javolution API recently, I was noticing just how great Jean-Marie had done with his Javadoc. Everything was so clear, there were links and examples all over the place, etc. So I started reading through the source code to get an idea of how I could improve my Javadoc and noticed one major difference that I have since adopted: The @link construct.

The @link construct is a slick Javadoc tag that pulls double-duty automatically. The typical format of a @link construct looks like this:

/** Calling this method will return a {@link String} with the user’s name */

public String getUserName();

Where the String is a class in the classpath of the project (this argument will actually require an import statement to be added if there isn’t one already).

Another example, like when you want to reference an inner class and a method, looks like this:

/** Used to get the cached result of {@link AbstractDocument.Content#createPosition(int) } */

public Position getCachedPosition();

You can see when accessing inner classes and static members using the dot-notation is what we would expect, but when accessing methods we have to denote those with the # sign.

The beauty of this tag is that depending on how you have your API-linking setup during the Javadoc generation stage the behavior of @link seems to be as follows:

1. If the class referenced is accessible given the current scope of linked Javadoc, make the class a hyperlink over to that classes’s Javadoc page.
2. If the class referenced is not accessible, simply wrap it with <code></code> tags to make it stand out in the doc as a code artifact.

So not only do I get to stop wrapping everything with <code></code> tags, but in addition to that, I automatically get hyperlinked Javadocs all over the place for free.

As an example I regenerated some Javadoc I had been working on and it’s about 20% more helpful now as a reader of the API because I no longer need to read a class name, remember it, go search the class listing and drill down into it. I can just click it and keep reading as I learn.

I realize this feature has likely been there since Javadoc 1.0, but I have to thank Jean-Marie’s excellent API for motivation to go figure out how to use it. I hope it helps you too.