javadoc

Generate documentation for Java source code and save the result in a directory

$ javadoc -d [path/to/directory]/ [path/to/java_source_code]

$ javadoc -docencoding [UTF-8] [path/to/java_source_code]

$ javadoc -exclude [package_list] [path/to/java_source_code]

javadoc [options] [packagenames] [sourcefiles] [@files]

packagenames: Specifies a series of package names to be documented. The javadoc tool searches for source files in the directories specified by -sourcepath.
sourcefiles: Specifies one or more Java source files (e.g., MyClass.java) to be processed. The javadoc tool processes these files regardless of their package.
@files: Reads command-line arguments (options, package names, source file names) from a file. Each argument can be separated by spaces or newlines.

-d
    Sets the destination directory where javadoc saves the generated HTML files.

-sourcepath
    Specifies the path javadoc uses to find source files for package names.

-classpath
    Specifies the path javadoc uses to find referenced classes.

-doclet
    Specifies an alternative doclet to generate output in a different format (e.g., XML).

-tag
    Allows adding a custom tag. locations specifies where the tag is valid (e.g., a for all, t for types, m for methods).

-private
    Shows all classes and members (most permissive).

-protected
    Shows protected and public classes and members (default).

-package
    Shows package, protected, and public classes and members.

-public
    Shows only public classes and members (least permissive).

-version
    Includes the @version paragraph in the generated documentation.

-author
    Includes the @author paragraph in the generated documentation.

-link
    Creates links to existing Javadoc documentation at the specified url.

-linksource
    Includes HTML versions of the source files and creates links to them from the standard HTML documentation.

-help
    Prints a summary of the standard options.

-verbose
    Prints messages about the Javadoc tool's status while it's running.

-encoding
    Specifies the source file encoding name (e.g., UTF-8).

-charset
    Specifies the HTML character set for the generated documentation (e.g., UTF-8).

-stylesheetfile
    Specifies the path to an alternative HTML stylesheet file.

-windowtitle
    Specifies the text to be placed in the browser window's title.

-doctitle
    Specifies the title of the generated documentation, placed near the top of the overview summary page.

-header
    Specifies HTML text to be placed at the top of each output file.

-footer
    Specifies HTML text to be placed at the bottom of each output file.

-bottom
    Specifies HTML text to be placed at the very bottom of each output file, below the navigation bar.

-splitindex
    Splits the index into multiple files, one for each letter of the alphabet.

-nodeprecated
    Excludes the generation of any deprecated API information.

-notree
    Excludes the class/interface hierarchy from the generated documentation.

-noindex
    Excludes the index from the generated documentation.

-nohelp
    Excludes the HELP link from the navigation bar.

-nonavbar
    Excludes the navigation bar from the top and bottom of generated pages.

-serialwarn
    Generates warnings for Serializable classes that do not define a serialVersionUID field.

The javadoc command is a crucial tool in the Java Development Kit (JDK) used to generate HTML-formatted API documentation directly from Java source files. It parses special "Javadoc" comments, which are multi-line comments starting with /** and ending with */, preceding declarations of classes, interfaces, methods, and fields. These comments often contain structured tags like @param, @return, @throws, and @see, which javadoc interprets to produce well-organized and navigable documentation. The generated documentation typically includes an overview, package summaries, class and interface details, method and field descriptions, and cross-references, providing a comprehensive reference for developers. This process automates the creation of professional API documentation, significantly aiding in code understanding, maintenance, and collaboration across development teams. It transforms plain text comments into a structured, hyperlinked web of information, making it an indispensable part of the Java development workflow.

javadoc is part of the Java Development Kit (JDK) and requires a JDK installation to be present on the system. It heavily relies on the correct syntax and meaningful content of Javadoc comments within the source code; poor commenting leads to poor documentation. For very large projects, generating documentation can be time-consuming and resource-intensive. The quality and completeness of the generated API documentation are directly proportional to the quality and thoroughness of the Javadoc comments in the source code.

Javadoc comments begin with /** and end with */. They precede declarations and can include a main description followed by block tags. Common block tags include:
@param <name> <description>: Describes a method parameter.
@return <description>: Describes the return value of a method.
@throws <class-name> <description>: Describes an exception that a method might throw.
@see <reference>: Adds a 'See Also' link to related content (class, method, URL).
@author <name>: Specifies the author(s) of the code.
@version <text>: Specifies the version of the code.
@since <version>: Indicates when the feature was added.
Javadoc comments can also contain inline HTML tags for richer formatting (e.g., <code> for code snippets, <pre> for preformatted text), though the output is restricted to <b>, <i>, <br> for this output format.

To generate documentation for a single Java file MyClass.java in the current directory, outputting to a subdirectory named docs:
javadoc -d docs MyClass.java

To generate documentation for an entire package com.example.mypackage, assuming source files are in src directory:
javadoc -d api -sourcepath src com.example.mypackage

The javadoc tool was introduced as a core utility with the initial releases of the Java Development Kit (JDK), providing developers with an automated way to produce API documentation. It has evolved significantly with subsequent Java versions, incorporating new features, supporting additional Javadoc tags, and improving output customization options. From its inception, it has been the de facto standard for documenting Java APIs, making the vast libraries of Java readily understandable and accessible to developers worldwide. Its consistent presence and enhancements reflect its critical role in maintaining the discoverability and usability of Java codebases.

javac(1), java(1), jar(1)