javadoc — API documentation

Overview

javadoc turns /** … */ doc comments into browsable HTML API documentation. For a library, the javadoc is the public contract as most users experience it; the tool also enforces a useful discipline because -Xdoclint fails builds on malformed or missing documentation.

Key points

• Doc comments: first sentence becomes the summary; block tags @param, @return, @throws, @since, @deprecated; inline tags {@link}, {@code}, {@inheritDoc}, {@value}.
• Snippets (JEP 413, Java 18): {@snippet …} embeds example code either inline or from external files (class=/file= with @highlight/@replace markup) — external snippets can be compiled and tested, ending the era of rotting code examples.
• Doclint: -Xdoclint:all (or scoped groups like reference, syntax) validates comments; commonly -Xdoclint:none is used to silence third-party noise — better to scope it.
• Doclets: the output backend is pluggable via the Doclet API; the standard HTML doclet is the default, custom doclets extract metadata or generate other formats.
• Search & modern output: current javadoc emits a client-side search index and supports --link/--linkoffline to cross-link external APIs (e.g. the JDK's own docs).
• Build integration: maven-javadoc-plugin builds the -javadoc.jar Maven Central requires; Gradle's javadoc task ditto — publishing docs is a release-pipeline step, not a manual invocation.

Examples

javadoc -d docs --release 21 -Xdoclint:reference \
        --link https://docs.oracle.com/en/java/javase/21/docs/api/ \
        -sourcepath src -subpackages com.example

Related

• The JDK, the JRE & their tools — parent catalog of the toolchain.
• javac — shares the compiler front end; doc comments are parsed with the same model.
• Build ecosystem — javadoc jars as a standard publishing artifact.