Javadoc Cheat Sheet

Overview

Javadoc is the standard documentation tool included with the Java Development Kit (JDK). It parses specially formatted comments in Java source code and generates comprehensive HTML API documentation. Javadoc has been the standard for Java documentation since JDK 1.0 and is used by virtually every Java library and framework.

Javadoc comments use a specific syntax starting with /** and support a rich set of tags for describing parameters, return values, exceptions, cross-references, and more. The generated output includes class hierarchies, package summaries, search functionality, and navigable HTML pages.

Installation

# Javadoc is included with the JDK
javadoc --version

# Install JDK if needed (Ubuntu/Debian)
sudo apt install default-jdk

# macOS via Homebrew
brew install openjdk

# Fedora/RHEL
sudo dnf install java-latest-openjdk-devel

Basic Usage

# Generate docs for a single file
javadoc MyClass.java

# Generate docs for a package
javadoc -d docs com.example.mypackage

# Generate docs for multiple packages
javadoc -d docs -sourcepath src \
  com.example.core com.example.utils

# Generate with classpath dependencies
javadoc -d docs -sourcepath src \
  -classpath lib/dependency.jar \
  com.example.mypackage

# Recursively process sub-packages
javadoc -d docs -sourcepath src \
  -subpackages com.example

CLI Options

Option	Description
`-d <dir>`	Output directory
`-sourcepath <path>`	Source file directories
`-classpath <path>`	Classpath for dependencies
`-subpackages <pkg>`	Recursively process sub-packages
`-exclude <pkg>`	Exclude specific packages
`-public`	Show only public members
`-protected`	Show protected and public (default)
`-private`	Show all members
`-author`	Include @author tags
`-version`	Include @version tags
`-link <url>`	Link to external API docs
`-doctitle <title>`	Document title
`-windowtitle <title>`	Browser window title
`-encoding <enc>`	Source file encoding
`-Xdoclint:all`	Enable all lint checks

Comment Syntax

Basic Structure

/**
 * Brief summary sentence ending with a period.
 *
 * <p>Extended description can span multiple paragraphs.
 * HTML formatting is supported in descriptions.</p>
 *
 * @tag value description
 */

Class Documentation

/**
 * A thread-safe cache implementation with configurable expiration.
 *
 * <p>This cache uses a ConcurrentHashMap internally and supports
 * both time-based and size-based eviction policies.</p>
 *
 * @param <K> the type of keys maintained by this cache
 * @param <V> the type of mapped values
 * @author Jane Doe
 * @version 2.1.0
 * @since 1.0.0
 * @see ConcurrentHashMap
 */
public class Cache<K, V> { }

Method Documentation

/**
 * Retrieves a value from the cache by its key.
 *
 * <p>If the key exists but the entry has expired, this method
 * returns {@code null} and removes the stale entry.</p>
 *
 * @param key the key whose associated value is to be returned
 * @return the cached value, or {@code null} if not found
 * @throws NullPointerException if the key is {@code null}
 * @see #put(Object, Object)
 * @since 1.0.0
 */
public V get(K key) { }

Tags Reference

Block Tags

Tag	Description
`@param name desc`	Method/constructor parameter
`@return desc`	Return value description
`@throws type desc`	Exception that may be thrown
`@see reference`	Cross-reference to other element
`@since version`	Version when API was added
`@deprecated desc`	Mark as deprecated with reason
`@author name`	Author of the class
`@version text`	Version of the class
`@hidden`	Hide from generated docs (JDK 9+)

Inline Tags

Tag	Description
`{@link Class#method}`	Hyperlink to element
`{@linkplain Class#method text}`	Plain text link
`{@code code}`	Inline code (no HTML)
`{@literal text}`	Literal text (escapes HTML)
`{@value #FIELD}`	Display constant field value
`{@inheritDoc}`	Inherit from parent/interface
`{@index term}`	Add to search index (JDK 9+)
`{@snippet :}`	Code snippet (JDK 18+)

Configuration with Maven

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <version>3.6.3</version>
  <configuration>
    <source>17</source>
    <show>protected</show>
    <author>true</author>
    <version>true</version>
    <doctitle>My Library API</doctitle>
    <links>
      <link>https://docs.oracle.com/en/java/javase/17/docs/api/</link>
    </links>
  </configuration>
</plugin>

# Generate docs with Maven
mvn javadoc:javadoc

# Generate Javadoc JAR
mvn javadoc:jar

Configuration with Gradle

javadoc {
    options {
        title = "My Library API"
        memberLevel = JavadocMemberLevel.PROTECTED
        author = true
        version = true
        links 'https://docs.oracle.com/en/java/javase/17/docs/api/'
        encoding = 'UTF-8'
        charSet = 'UTF-8'
    }
}

Advanced Usage

Code Snippets (JDK 18+)

/**
 * Example using the new snippet tag:
 *
 * {@snippet :
 * Cache<String, String> cache = Cache.builder()
 *     .maxSize(100)             // @highlight
 *     .expireAfterWrite(
 *         Duration.ofMinutes(5) // @highlight
 *     )
 *     .build();
 * }
 */

Doclint Checks

Check	Description
`accessibility`	Accessibility issues (alt text, etc.)
`html`	Invalid HTML in comments
`missing`	Missing Javadoc comments or tags
`reference`	Broken @see or @link references
`syntax`	Invalid Javadoc syntax

# Enable all checks
javadoc -Xdoclint:all ...

# Disable specific check
javadoc -Xdoclint:all,-missing ...

Troubleshooting

Issue	Solution
”package does not exist”	Add missing JARs to `-classpath`
Missing cross-references	Use `-link` to connect to external API docs
HTML warnings in comments	Use `{@code}` instead of raw `<code>` tags
Encoding errors	Set `-encoding UTF-8 -charset UTF-8`
Private members not shown	Use `-private` flag
@author tags not appearing	Add `-author` flag to command
Module system conflicts	Use `--add-modules` or `--module-source-path`
Too many warnings	Use `-Xdoclint:none` to suppress, then fix incrementally