javadoc -d: Generate Java API Documentation
javadoc -d <dir> generates HTML API documentation from Java classes and their Javadoc comments.
javadoc ships with the JDK and turns /** ... */ comments into a browsable API site. In CI the sharp edge is doclint, which fails on malformed HTML or missing tags.
What it does
javadoc compiles the specified Java sources enough to read their declarations and doc comments, then writes an HTML documentation set to the -d output directory. It validates comments with doclint unless you disable it.
Common usage
javadoc -d build/docs/api -sourcepath src/main/java com.example
# turn off strict doc linting if it is too noisy
javadoc -d build/docs/api -Xdoclint:none -sourcepath src/main/java com.example
# via Maven
mvn javadoc:javadocOptions
| Flag | What it does |
|---|---|
| -d <dir> | Destination directory for generated docs |
| -sourcepath <path> | Where to find source files |
| -subpackages <pkg> | Recursively document a package tree |
| -Xdoclint:<group> | Control doc linting: all, none, or html/syntax/reference |
| -classpath <path> | Classpath for referenced libraries |
| -quiet | Suppress non-error messages |
In CI
Since JDK 8, doclint fails the build on broken HTML or bad @param references. Fix the comments, or scope it with -Xdoclint:all,-missing to allow missing tags while still catching malformed HTML. For Maven, configure failOnError and doclint in the javadoc plugin.
Common errors in CI
error: unknown tag: pre or warning: no @param for x come from doclint; error: bad use of '>' flags raw angle brackets in a comment. javadoc: error - No source files for package com.example means -sourcepath or the package name is wrong. javadoc: error - Illegal package name usually means a stray file passed where a package was expected.