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.