Easy documentation with Javadoc

There’s probably nothing programmers hate more than documenting their code. Even doing timesheets takes second place on the list of things programmers hate to do.

Fortunately help is at hand.

The developers of Java recognised the problem and made life easy for us. They developed a tool called javadoc which generates standard HTML documentation from comments we write in our Java source code.

Javadoc really is easy

The javadoc tool has been available in the JDK since version 1.0. All the standard Java API documentation has been generated with it, so you should already be familiar with the output (you do read the API documentation, don’t you?).

All we need to do is to write specific Javadoc comments while we are developing our code (you do comment your code, don’t you?). A Javadoc comment start with a /** and end with a */, and can span as many lines as we need. The Javadoc comment must be placed before the declaration of a class, a field, a constructor, and/or a method. We can also include HTML tags within the Javadoc comments.

Within our Javadoc comments, we can also add additional Javadoc tags. The javadoc tags generate additional information from our source code. These tags all start with an @ sign. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk).

Examples of these case-sensitive tags include:

• @author
• @deprecated
• @exception
• @param
• @return
• @see
• @since
• @throws
• @version

A simple Javadoc example

Here’s a simple example:

/**
 * A class representing an employee. This is a model 
 * object within our domain.
 * The domain class hierarchy is as follows:
 * 
 *
 * @author  John Smith
 * @version 3.14
 * @see     com.example.Person
 */

public class Employee extends Person {
   ...
}

A simple example of a method comment follows:

/**
 * Converts the string argument containing a signed decimal
 * integer into an {@code int} value.
 *
 * @param str  a {@code String} containing the decimal 
 * number to be converted.
 * @return     the {@code int} value represented by 
 * the argument.
 * @exception  NumberFormatException  if the string 
 * cannot be converted to a decimal number.
 */

public int convert(String str) throws NumberFormatException {
   ...
}

Watch out for proper sentence construction and punctuation! The first sentence (ending with the first period) will be used as the description in the summary section, while the entire Javadoc comment will be used in the detail section.

How Javadoc works

We can run javadoc on whole packages and/or individual source files. The javadoc tool parses the declarations, Javadoc comments and tags in our source code, and generates a set of corresponding HTML pages. These describe the public and protected classes (by default; this can be changed), nested classes, interfaces, fields, constructors and methods. When generating HTML documentation, javadoc adds additional cross-reference links to documented elements such as:

• Declarations (return types, argument types, and field types).
• See Also sections that are generated from @see tags.
• Exceptions generated from @throws tags.
• Summary tables of packages, classes and members.
• Package and class inheritance trees.
• The index file.

If we’re disciplined when writing code (you are a disciplined programmer, right?), we can reduce the burden of writing code documentation afterwards. An added benefit is that our documentation will have the same format as all the other standard Java API documentation out there, and can be easily used by other Java programmers.

For further information on how to use javadoc, Javadoc tags and javadoc options, please refer to the JDK tool documentation.

I’m always interested in your opinion, so please leave a comment. Your feedback helps me write tips that help you.