Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท Language Features by Version

Javadoc documentation comments

Reference for Javadoc: comment syntax, block and inline tags such as @param, @return and {@code}, Markdown comments (Java 23), and running the javadoc tool.

Javadoc turns specially formatted comments in your source into HTML API documentation. A documentation comment starts with /**, ends with */, and sits directly before a class, interface, field, constructor or method. The first sentence becomes the summary shown in lists; the rest, plus tags like @param and @return, fill the detail page. IDEs also show these comments as pop-up help while you type.

Documentation comments describe what the code promises, not how it works inside: what the parameters mean, which values are allowed, what is returned, when exceptions are thrown, which version added it. Since Java 23 you can also write them in Markdown with lines that start with ///.

Java
/**
 * Adds two numbers without overflow checks.
 *
 * @param a the first operand
 * @param b the second operand
 * @return {@code a + b}
 * @throws IllegalArgumentException never; shown only as an example
 */
public static int add(int a, int b) { return a + b; }

Try it

The JDK's documentation tool is itself a library, so this example writes a small source file to a temporary folder, runs javadoc on it and checks the generated HTML. The folder is deleted afterwards.

Java Running javadoc from a program

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Doclint finds missing documentation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Common tags

Tag Kind Use
@param name text block Describes a parameter (@param <T> text for a type parameter, @param x for a record component in the class comment).
@return text block Describes the result of a non-void method.
@throws Type text (or @exception) block When and why the exception is thrown.
@see ref block A "See also" link.
@since version block The version that introduced the API.
@deprecated text block Why it is deprecated and what to use instead. Pair with @Deprecated.
@author, @version block Metadata, shown only when requested.
{@code text} inline Monospace, no HTML processing: {@code List<String>}.
{@link Type#member label} inline A hyperlink to another element.
{@literal text} inline Escapes <, > and & without monospace.
{@inheritDoc} inline Copies text from the overridden method.
{@snippet ...} inline A compiled, checkable code sample (Java 18).
{@index term}, {@value}, {@summary} inline Search index entry, constant value, custom summary.

Markdown comments (Java 23)

Java
/// Adds two numbers.
///
/// - Overflow wraps around.
/// - Use [Math#addExact(int, int)] for a checked version.
///
/// @param a the first operand
/// @param b the second operand
/// @return the sum
public static int add(int a, int b) { return a + b; }

In Markdown mode, [Type#member] creates links, backticks create code, and tags still start with @. Use one style per comment.

Usage notes

  • The first sentence is the summary: end it with a period and a space. Make it a complete statement ("Returns the length of this string.").
  • Use {@code ...} instead of raw < and >; HTML in comments must be valid, so write &lt; or {@literal <}.
  • Document the contract: preconditions, null handling, thread safety, side effects, complexity when it matters. Do not repeat the method name in other words.
  • Overriding methods inherit documentation automatically; add your own text only where behavior differs.
  • Run javadoc -Xdoclint:all (or enable it in the build) to find missing @param/@return, broken links and malformed HTML.
  • Commands: javadoc -d docs -sourcepath src -subpackages com.example. Maven's maven-javadoc-plugin and Gradle's javadoc task wrap it.
  • Document public and protected API thoroughly; by default javadoc skips private members.
  • package-info.java documents a package, module-info.java a module, and overview.html the whole project.