Javadoc

❗ Note: This section introduces an important Java tool: Javadoc. It’s not a part of the AP CS A exam. The purpose is only to familiarize students with the functionalities of Java.

Overview

Javadoc parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages describing (by default) the classes, interfaces, constructors, methods, and fields.

Javadoc’s comments structure is similar to a regular multi-line comment, but the key difference is the extra asterisk at the beginning:

Single-line comment:

// It is a single-line comment

Multi-line comment:

/*
 * It is a multi-line comment
 */

Javadoc style comment:

/**
 * It is a Javadoc style comment
 */

Format of Javadoc

The comments are commonly made up of two sections:

• Description of what we are commenting
• HTML tags marked with an @ symbol

Javadoc at the class level

This is a class level Javadoc comment:

/**
* ClassA is used to . . .
* 
* Please see the {@link myMethod(int, int) myMethod} method.
* @author Carol Smith
* 
*/

Notice, there are two different block tags:

• {@link} provides an inline link to a referenced part of our source code.
• @author provides the name of the author who added the class.

Javadoc at the field level

This is a field level Javadoc comment:

/**
* The name of an employee isn't confidential
*/
public int name;

Javadoc at the method level

This is a method level Javadoc comment:

/**
 * <p>This is a simple description of the method. . .
 * </p>
 * @param two integers
 * @return the smallest of them
 * @since 1.0
 */

Let’s go over the tags:

• @param provides a description of the method’s parameter that should be expected.
• @return provides a description of what a method will return.
• @since specifies which version of the class, field, or method was added to the project.

What we have seen so far is just the surface of Javadoc. There’s much more in Javadoc. We’ll keep it short since it’s not a part of our exam.

📌 Note: If you want to read more about Javadoc, click here.

---