Javadoc in Java: Documentation Comments and Tags - Quiz

Javadoc is the documentation generator for Java: it builds HTML documentation from special /** ... */ comments in the source code. It ships with the JDK as the javadoc command, and the official Java SE API documentation is generated with it.

Its main job is to keep documentation from drifting away from the code. The description sits right above the declaration, so you see it on every change, the IDE shows it in tooltips, and the HTML version (a page per class, package lists, an index and a search box) is rebuilt with one command.

Javadoc comments document classes, interfaces, enums and records, fields, constructors and methods, as well as packages (the package-info.java file) and modules (module-info.java).

A doc comment starts with /**, ends with */ and is placed directly before the declaration of a class, field, constructor or method — before any annotations and modifiers. Regular /* ... */ and // comments are ignored by javadoc.

• The main description comes first. Its first sentence (up to the first period followed by a space) goes into the summary tables of the package and the class.
• The text is HTML: paragraphs are separated with <p>, lists use <ul>/<li>; your own headings should be <h2> or lower, because javadoc generates the <h1> itself. Leading asterisks are discarded.
• Block tags (@param, @return and others) start with @, are the first thing on a line and come after the description.
• Inline tags ({@code}, {@link}) are written in curly braces anywhere in the text.

Since Java 23 (JEP 467) a doc comment can also be written in Markdown — as lines starting with ///.

• @param name description — a method or constructor parameter; the name must match the signature. A type parameter is written as @param <T>.
• @return description — the return value (not for void); since Java 16 there is also the inline form {@return ...}.
• @throws Class description — an exception and the condition that throws it, unchecked ones included; @exception is the old synonym.
• {@link Class#member} — a link to a class, method or field; for a method with parameters list their types: {@link String#indexOf(int)}.
• {@code text} — code in a monospace font that escapes <, > and & by itself.
• @deprecated — why an element is outdated and what to use instead (together with the @Deprecated annotation).

Less common are @author, @version, @since, @see, {@value} (the value of a constant), {@inheritDoc} (the description from the overridden method) and {@snippet} (a code example, since Java 18).

With the javadoc command from the JDK: pass it the source files or packages and an output directory.

javadoc -d docs -sourcepath src -subpackages com.example -author -version -encoding UTF-8

• -d — where to write the HTML; -sourcepath and -subpackages — where to find the sources and which packages to process;
• -author, -version — include the @author and @version tags;
• -private — document private elements too (by default only public and protected);
• -encoding UTF-8 — the source encoding (UTF-8 is the default since JDK 18).

The result is index.html, a page per class, package-summary.html, overview-tree.html, index-all.html, and lists of deprecated elements and constant values. In Maven the same is done by mvn javadoc:javadoc and mvn javadoc:jar (the archive required for Maven Central), in Gradle by ./gradlew javadoc.

The IDE shows a comment in a popup straight from the sources, without generating any HTML. In IntelliJ IDEA the Quick Documentation popup opens with Ctrl+Q (Windows, Linux) or F1 (macOS), and also on mouse hover over a name. Type /** above a method and press Enter, and IntelliJ IDEA or Eclipse creates a template with @param, @return and @throws taken from the signature.

Library docs may be missing because the compiler drops all comments, so the jar with bytecode contains none. Attach the sources or the javadoc archive (*-sources.jar, *-javadoc.jar), for example with Download Sources in IntelliJ IDEA.