A brief look at the Javadoc format

Java supports a third type of comment which is used by the javadoc tool in the creation of documentation files. This type of comment is generally referred to as javadoc comments and is very similar to the multi-line comment. Javadoc comments start with a slash and two asterisks ("/**") and end with an asterisk and a slash ("*/"). These comments are placed right before the start of a class, the start of a class variable, or the start of a method in a class and contain a description of that item. In addition to a description the javadoc comment may contain certain keywords which aid the javadoc compiler.

The power of the javadoc comment comes into play when the file(s) the comments are in are compiled with the javadoc tool. This tool creates a set of html document files describing the classes, methods, and class variables that a program uses. As long as proper javadoc comments are used, creating documentation for a program is a simple process of running the javadoc tool.

Javadoc comments that are placed above the class statement describe the class as a whole. This is a good place to describe the class as a whole and how to use the class. There are a variety of keywords that can be used here, but the two that I use are the @author keyword and the @version keyword.

The @author keyword is for naming the person or people who wrote the source code. It uses the format:
@author name list

The @version keyword is for assigning a version number to the source file. it uses the format
@version version number

Javadoc comments that are above a method also have a number of special keywords that can be useful. The four that I use the most are @param, @see, @causes and @return.

The @param statement is for describing the parameters that are being passed to a method. This is very useful as it explains to the user of the class what the parameters being passed to the method are. If there are restrictions on the values that should be passed to a method, this would be the ideal place to explain them. The format is
@param variable_name description

When you wish to direct the reader of your documentation to another method that may be important to understanding or is related to the method they are reading about, the @see statement is handy. The javadoc program uses these statements in the see also section of a method description. The format is
@see class

If your method may cause an exception to be thrown, you should let the documentation reader know about the required exceptions handling by using the @throws statement. The format is
@throws exception description

Finally, if the method returns a value, the @return statement should be used. This describes what the method returns and uses the format
@returns description

There are many other javadoc tags, so be sure to read the javadoc documentation for a description of them and for more information on using the javadoc tool.

If you are writing a library of classes, the javadoc tool is indispensable. By making sure that all methods have a javadoc comment block associated with it, generating documentation for the classes takes only a few minutes. One way of making sure that you have javadoc comments is by making a javadoc comment block whenever a new method is created. Describing what a method does is not always necessary, but I always try to describe the method parameters and what the method returns.

Many IDE's support automatic javadoc generation. Even if your tools do not support automatic javadoc generation, the tool is not that complex to use. It is simple enough to create a batch file or script to generate documentation so there really is no reason not to take advantage of this excellent tool.

While javadoc is obviously useful for library documentation, I have tried to get into the habit of using the javadoc comments in all my classes. While you may never need to generate html documentation for the main source code to the application you are developing, it is still useful to have the javadoc comments in the code. The comments are easy to read, so any programmer going through the source code can understand the parameter comments that are within the javadoc comment block.