Javadoc Guidelines¶

Documentation comments, also known as Javadoc comments, begin with /** (two stars) and end with */ (one star). These comments provide information about classes and methods. The official documentation for the Java library was generated almost entirely by Javadoc comments. VS Code and other IDEs read Javadoc comments to provide hints as you type.

Learning to write Javadoc comments is an important professional skill. This page summarizes best practices for writing Javadoc comments.

Class Example¶

Class comments should have:

A one-sentence (or more) description of what the class is.
An @author tag containing your full name (first and last).
A @version tag containing the date of the assignment.

/**
 * The traditional first program.
 *
 * @author Brian Kernighan
 * @version 05/23/1995
 */
public class HelloWorld {
}

Method Example¶

Method comments should have:

A one-sentence (or more) description of what the method does.
A @param tag that explains each parameter by name.
A @return tag that describes the return value.

/**
 * Display a prompt, followed by ": ", and return the next line of
 * user input. The input is entered on the same line as the prompt.
 *
 * @param in the Scanner to use
 * @param prompt the text to display
 * @return the user's input
 */
public static String inputLine(Scanner in, String prompt) {
}

Note

The description at the beginning of the comment should be a complete sentence that ends with a period. Checkstyle will complain if you don't put a period at the end of your sentence. In contrast, the @param and @return comments should be short phrases that do not end with a period.

What Not to Do¶

Common mistakes when writing @param tags include:

Including a dash or other punctuation:
```
@param in - the Scanner to use
```
Putting the data type in the comment:
```
@param in Scanner the Scanner to use
```
Starting the comment with a verb:
```
@param in is the Scanner to use
```

Common mistakes when writing @return tags include:

Putting the data type in the comment:
```
@return String the user's input
```
Including the method's variable name:
```
@return inputLine the user's input
```

Troubleshooting¶

If you get a message like @param tag must be preceeded by a blank line, it probably means that there is extra whitespace on the line above it. Delete anything (even if you can't see it) that is after the asterisk on the "blank" line.