A Javadoc comment begins with /** (two asterisks, distinct from an ordinary /* comment) placed immediately above the declaration it documents. Inside, tags like @param, @return, @throws, and @see describe specific aspects of the method or class in a structured way. Running the javadoc command-line tool over a codebase extracts every such comment and generates a full set of cross-linked HTML pages — this is literally how the official Java API documentation itself is produced from the JDK's own source.
A documented method
The first sentence becomes the short summary shown in class-level overview tables; the full comment appears on the method's own detail page.
/**
* Divides one number by another.
* <p>
* This method does not handle a zero divisor gracefully — callers
* should validate input beforehand.
*
* @param numerator the number to be divided
* @param divisor the number to divide by, must not be zero
* @return the result of numerator divided by divisor
* @throws ArithmeticException if divisor is zero
*/
public double divide(double numerator, double divisor) {
if (divisor == 0) {
throw new ArithmeticException("Cannot divide by zero");
}
return numerator / divisor;
}Generating HTML documentation
The generated output includes a searchable index, cross-links between classes (a method's @return type, if it's a project class, becomes a clickable link), and inherited-method documentation — all without writing a single line of HTML by hand.
$ javadoc -d docs Calculator.java
$ open docs/index.html // browsable HTML, generated entirely from the comments aboveCommon tags: @param, @return, @throws, @see, @deprecated
@deprecated, paired with the @Deprecated annotation covered in the previous topic, explains WHY something is deprecated and what to use instead — the annotation triggers the compiler warning, while the Javadoc tag supplies the human-readable explanation that shows up in the generated docs and IDE tooltips.
/**
* @deprecated Use {@link #divideChecked(double, double)} instead,
* which returns an Optional rather than throwing.
*/
@Deprecated
public double divide(double numerator, double divisor) { /* ... */ }