How to write Java Documentation

CPE102 - How to write simple Java documentation for the javadoc tool

The javadoc-style of comments allows a utility that comes with the Java development environment (called javadoc) to read your source code and generate html files documenting your class. It is very easy to write the comments and use the utility to generate very readable and useful documentation for classes you write. We will be using a subset of the supported features, if you would like to learn more about writing javadocs see the how-to documentation provided by Oracle.

You will be documenting the public methods in some of the Java files you write this quarter. In a typical development effort you would document all of the public methods in all of the source files but, since this is a learning environment and in the interest of reducing your workload, I will only require you to document some of your code - hopefully enough to ensure that you know how to use the tool!

To document a method you must include a comment block immediately preceeding the method you are documenting similar to this one (note that the items in bold are bold to draw your attention to them, not necessary (or possible) to bold in your source file):

1 /**
2 * A sentence (must be terminated with a period, '.') describing at a high level what
3 * this method does. The first sentence will be part of the brief description that is
4 * generated by the javadoc tool. Any additional text will be part of the detailed
5 * description.
6 *
7 * @param someValue A description of what this parameter is for. Should include
8 * restriction, if any, on the values passed in.
9 *
10 * @param anotherValue A description of what this parameter is for. Should include
11 * restriction, if any, on the values passed in.
12 *
13 * @return A description of what value(s) are returned and under what specific
14 * circumstances.
15 *
16 * @throws InvalidArgumentException describe when this exception is thrown by the
17 * method.
18 */
19 public double someMethod(String someValue, int anotherValue)
20 {
21 // Code for method not shown
22 }

Let's examine the example above in detail:

First, you must begin a javadoc comment block with /** (see line 1 above). Both asterisks are required. The block must be terminated with an */ (see line 18 above).
Notice the use of the phases brief description and detailed description in the text on lines 3 and 4 above. The first sentence of your description will be the brief description and the detailed description will be the entire description. Take a look at some documentaion in the Java Standard Library to get a feel for what these phrases mean and examples of how they are typically written.
Next you document any and all parameters to the method using the @param tag (lines 7 & 10), one tag for each parameter in the order they appear in the method's parameter list. You must state the name of the parameter exactly as it appears in the actual method or an error will occur when you generate the html documentation. If the method has no parameter you do not write any @param tags.
Now you document the return, if any, for the method using the @return tag (line 13). If the method has a void return-type you do not write the @return tag.
Finally, you document the exceptions, if any, that the method is designed to throw during execution using the @throw tag (lines 16), one tag for each exception the method might throw. If the method does not, by design, throw any exceptions you do not write any @throws tags.

When you have completed documenting the class you are ready to generate the HTML files using the javadoc utility included with the JDK (Java Development Kit). See How to Generate JavaDoc HTML Files for instructions on how to proceed.