Documentation Comment

A Java documentation comment (Javadoc) is a specialized block comment parsed by the javadoc utility to generate structured, HTML-based API documentation. It is strictly placed immediately preceding the declaration of a module (via module-info.java), package (via package-info.java), class, interface, record, enum, annotation, constructor, method, or field.

Syntax Structure

A documentation comment begins with a forward slash and two asterisks /** and terminates with an asterisk and a forward slash */. Intermediate lines conventionally begin with an asterisk *, which the parser automatically strips along with preceding whitespace.

/**
 * {@summary Parses a string into an integer and associates it with a generic identifier.}
 * Subsequent sentences provide a more detailed description of the element.
 * HTML tags such as <strong>bold</strong> or <ul><li>lists</li></ul> are valid here.
 *
 * @param <T> the type of the metadata tag associated with the parsing operation
 * @param input the string representation of the number
 * @return the parsed integer value
 * @throws NumberFormatException if the string does not contain a parsable integer
 */
public <T> int parseNumber(String input) throws NumberFormatException {
    return Integer.parseInt(input);
}

Anatomical Components

A standard Javadoc comment is divided into two distinct sections:

1. Main Description: Begins immediately after the opening /**. Historically, the parser treated the first sentence (terminated by a period followed by a space, tab, or line terminator) as the concise summary statement used in index tables. In modern Java (Java 10 and later), the {@summary ...} inline tag is the robust standard for explicitly defining this summary text.
2. Block Tags Section: Begins with the first block tag (e.g., @param). Once the block tag section begins, no further main description text can be added.

Block Tags

Block tags are standalone markers placed at the beginning of a line (ignoring the leading asterisk) to define specific metadata about the API element.

• @param: Documents a method parameter, constructor parameter, or generic type parameter. For generic type parameters, the angle-bracket syntax is required (e.g., @param <T> description of the type parameter).
• @return: Documents the return value of a method. Omitted for void methods or constructors.
• @throws / @exception: Documents checked and unchecked exceptions that the method may propagate. Syntax requires the fully qualified or imported exception class name followed by the condition.
• @see: Generates a “See Also” reference to another API element, URL, or text.
• @since: Indicates the version of the software in which the element was introduced.
• @deprecated: Marks an element as obsolete. The description must include a migration path or alternative element.
• @version: Specifies the current version of the software (typically used at the class/interface level).
• @author: Identifies the creator of the code element.

Inline Tags

Inline tags are enclosed within curly braces {} and can be embedded anywhere within the main description or block tag descriptions.

• {@summary text}: Explicitly defines the text to be used as the summary sentence in index tables, overriding the legacy period-and-space parsing rule.
• {@code text}: Renders the enclosed text in a monospaced font and escapes HTML characters (e.g., < and >), preventing the parser from interpreting them as HTML markup.
• {@link package.class#member label}: Generates an inline HTML hyperlink pointing to the documentation of another specific API element.
• {@value}: When used on a static final field (a compile-time constant), it evaluates and displays the constant value of that field.

Parsing Mechanics

When the javadoc tool processes these comments:

• It ignores standard block comments (/* ... */) and end-of-line comments (// ...).
• It resolves fully qualified class names referenced in @see, @throws, and {@link} tags based on the current compilation unit’s imports.
• It directly passes embedded HTML markup to the generated output, meaning malformed HTML within the comment will result in malformed documentation pages.

Master Java with Deep Grasping Methodology!

Learn More