Beginner’s Guide to Using Javadoc

Written by Mike True, updated by Daniel Myungho Sim and Daniel Calabria

General Information: All individual entries in APIs generated by Javadoc require Javadoc-style comments in your .java source files to appear above the header of what they are to represent. This means that for information about your class to appear in the API you must have a Javadoc comment above it, for information about each of your methods to appear you must have an individual Javadoc comment above each method in your source file, and so on and so forth.

Javadoc comments are flagged by the API generator with the following outline:

/** (This begins the comment)

* (You would have information about the class, method, or field here)

* (More information)

*/ (This ends the comment)

JBuilder, if you type "/**" and enter, will create the other asterisks for you automatically and as you add more lines to the comment it will add more asterisks. If you are using a text editor on sparky or another UNIX system for your programming you will need to do this manually.

To make sure your comments are of legal syntax, check the lower left-hand pane in JBuilder to make sure a folder labeled "Javadoc Conflicts" does not appear. If you are using UNIX, use the command javadoc *.java and make sure that no errors or warnings appear.

Method Information: In most specifications you write, the first line of any class or method information will be a general overview of what that class or method does. To do this in Javadoc, simply type in plain text what you wish to write as the general information on the first informational line of the comment after the asterisk (it may expand onto multiple lines). You may use some of the additional text modifying tags that are further discussed below.

Supported Tags: Javadoc can be thought of as an enhanced version of HTML, which means that most basic HTML tags remain the same while a few others have been added. The added tags have been put there to make some aspects of specification writing with Javadoc easier. These tags include the ones for Returns:, Parameters:, and Throws:.

The general syntax of Returns: is to write @return on one line of the comment and on the following lines to write the information about what the method returns on the following line.

The syntax for Parameters: and Throws: are very similar. For each parameter or exception that the method has or throws, write @param <parameter name> or @throws <exception name> and follow on the next line with the appropriate description. This is to be repeated until all the parameters and exceptions have been accounted for. Below is an example of a method header preceded by the Javadoc comment that should be associated with it:

/**
 * A method that determines the quotient of two integers.
 * @param x
 *     The number that is going to be divided
 * @param y
 *     The number that x is going to be divided by
 * [Precondition to be discussed later]
 * @return
 *     The quotient that is the result of x/y.
 * @throws ArithmeticException
 *     Indicates that y is equal to zero.
 */
public static int divide(int x, int y) throws ArithmeticException

Unsupported Tags: Not all tags you need in your specification are supported in Javadoc, namely Preconditions: and Postconditions:. In order to make an unsupported tag appear in your API as if it were supported, use the following syntax:

@custom.TAG_NAME_MODIFY_THIS INSERT_CUSTOM_TAG_DESCRIPTION_HERE

In addition, it requires that you run javadoc in the command line prompt or in console with additional parameters.
For instance, in your console or command prompt, you need to run
javadoc filename -tag custom.TAG_NAME_MODIFY_THIS:a:"TAG_NAME_MDDIFY_THIS"

Examples are
/**
 * ... (Other Javadoc information as necessary) ...
 * @custom.precondition
 *     INSERT_YOUR_PRECONDITION_DESCRIPTION
 * @custom.postcondition
 *     INSERT_YOUR_POSTCONDITION_DESCRIPTION
 * ... (Other Javadoc information as necessary) ...
 */
Type the tag name on one line and what you want to appear in that field on the next. Here is the previous example again:

/**
 * A method that determines the quotient of two integers.
 * @param x
 *     The number that is going to be divided
 * @param y
 *     The number that x is going to be divided by
 * @custom.precondition
 *     y must not be equal to zero
 * @return
 *     The quotient that is the result of x/y.
 * @throws ArithmeticException
 *     Indicates that y is equal to zero.
 */

If this method was located in myfile.java, we can generate the corresponding Javadoc with the following command:
javadoc -tag custom.precondition:a:"Preconditions:" myfile.java

Additional Information: Other HTML tags can be used to modify the way text appears. For example, anything written in between <CODE> and </CODE> appears in a code type text. To make words appear bold, use the <STRONG></STRONG> pair of tags. For text modifications, look online for an HTML tutorial because most of the commands are the same.