Javadoc

One of the key features of a good library is comprehensive documentation of the API. Java helps a lot with this through the application of Javadoc comments in the library source. The standard Java library that every Java programmer needs to understand comes with that comprehensive documentation and you can use the same tools to document your own library.

Javadoc Comments

As you develop your code, you should be documenting the source with the standard Javadoc comments. Each class should have a Javadoc comment, each instance variable and method in the class should a Javadoc comment. For example, consider the following short snippet of source a method in my utility library:

/**
 * Set the background image to the resource specified by the URL.
 * 
 * @param url the URL from which to load the image.
 * 
 * @throws FileNotFoundException if the specified resource could not be
 *             located.
 */
public void setBackgroundImage(String url) throws FileNotFoundException
{
    URL resource = GridPanel.class.getResource(url);
    if (resource == null) {
        throw new FileNotFoundException("Could not locate the resource: \"" + url + "\"");
    }
    setBackgroundImage(new ImageIcon(resource).getImage());
}

If you are developing in Eclipse, you can automatically generate a template comment for most components by putting the cursor on the line immediately above the element and typing /** and the hitting return key. This will insert a comment that, for a method, contains the required tags for any parameters, exceptions and return value. You then only need to add the details...

When processing by the Javadoc tool, this would produce the chunk of Javadoc for the method shown here... A further advantage of using Javadoc is that most IDEs will display the associated documentation as a tooltip when the mouse is hovered over a particular item.

References

The official Oracle description of Javadoc is comprehensive, but rather dense.

However, you can find a good introductory Javadoc tutorial on the tutorialspoint site.

Eclipse has an export wizard that will automatically create the HTML documentation from your comments - here is the help file for the Eclipse Javadoc tool.

Finally, as an extended example, the complete documentation for my Java utility library is here...

Previous ...back to the standards overview