Javadoc: Comment Syntax & Core Tags

Javadoc is both a comment convention and the javadoc tool bundled with the JDK that generates browsable HTML API documentation directly from specially formatted comments colocated with the code they describe.

Basic Structure

/**
 * Calculates the total price including tax.
 *
 * <p>The tax rate is applied to the {@code basePrice}. This is a
 * detail paragraph -- the first sentence above is used as the
 * concise summary shown in generated summary tables/indexes.
 *
 * @param basePrice the price before tax, must be non-negative
 * @param taxRate the tax rate as a decimal (e.g. 0.08 for 8%)
 * @return the total price including tax
 * @throws IllegalArgumentException if basePrice is negative
 * @see #applyDiscount(double, double)
 * @since 2.4.0
 */
public double calculateTotal(double basePrice, double taxRate) {
    if (basePrice < 0) {
        throw new IllegalArgumentException("basePrice must be non-negative");
    }
    return basePrice * (1 + taxRate);
}

// javadoc comments start with /** (two asterisks) -- a plain /* */
// comment in the same position is NOT picked up by the javadoc tool.
// Must immediately precede the declaration -- no code/blank
// statements between the comment and what it documents.

Core Block Tags

• @param name description -- one per parameter, in signature order; the tool cross-references against the actual method signature.

• @return description -- for non-void methods, explains what the return value means.

• @throws ExceptionType description (alias @exception) -- one per exception the method may raise, explaining why/when.

• @since version -- which release a class/method was introduced in, for API-compatibility checking.

• @author name -- some teams use it, others avoid it since it can go stale (unlike git blame, it doesn't auto-update).

• @deprecated explanation -- pairs with the @Deprecated annotation (compiler warnings) to explain WHY and what to use instead.

Inline Tags

/**
 * Returns {@code true} if the list contains no elements.
 * See {@link #size()} for the element count.
 *
 * <p>Default timeout: {@value #DEFAULT_TIMEOUT_MS} ms -- this stays
 * automatically in sync with the constant's actual value.
 */
public static final int DEFAULT_TIMEOUT_MS = 5000;

// {@code ...}  -- monospace code formatting, auto-escapes < and >
// {@link ...}  -- clickable cross-reference, validated at generation time
// {@value ...} -- inserts a static final constant's actual literal value
// {@inheritDoc} -- copies documentation from the overridden method