man > javadoc(1)

📝 NAME

javadoc - Generates HTML pages of API documentation from Java source files.

🚀 Quick Reference

Use CaseCommandDescription
Document a packagejavadoc -d output_dir com.mypackageGenerate HTML for a package (source must be in corresponding directory)
Document with source pathjavadoc -d output_dir -sourcepath /src com.mypackageSpecify where to find source files for packages
Recurse into subpackagesjavadoc -d output_dir -sourcepath /src -subpackages javaDocument a package and all its subpackages
Exclude packagesjavadoc -d output_dir -sourcepath /src -subpackages java -exclude java.net:java.langExclude certain packages from recursive scan
Document specific source filesjavadoc -d output_dir Class.java Interface.javaGenerate docs for explicit list of source files
Add window titlejavadoc -windowtitle "My API" ...Set browser window/tab title
Link to external docsjavadoc -link http://example.com/api/ ...Link to other Javadoc output (requires package-list)
Set author/versionjavadoc -author -version ...Include @author and @version tags in output
Show only public classesjavadoc -public ...Limit documentation to public members
Custom docletjavadoc -doclet com.example.MyDoclet -docletpath /path ...Use a custom doclet instead of the standard HTML doclet

📖 SYNOPSIS

javadoc {packages|source-files} [options] [@argfiles]

packages — Names of packages to document, separated by spaces, e.g. java.lang java.awt. Use -subpackages to include subpackages.
source-files — Java source file names, separated by spaces, e.g. Class.java Object.java.
options — Command-line options (see Options).
@argfiles — Files containing lists of options, package names, or source file names.

📘 DESCRIPTION

The javadoc command parses declarations and documentation comments in Java source files and produces HTML pages describing the public and protected classes, interfaces, constructors, methods, and fields. You can run it on entire packages, individual source files, or both. When using packages, use -subpackages for recursion or pass explicit package names.

🔄 PROCESS SOURCE FILES

The javadoc command processes files that end in .java and meet these requirements:

Processing Links: During a run, cross-reference links are added for declarations, @see tags, {@link} tags, @throws tags, overrides, summary tables, inheritance trees, and the index. Use -link and -linkoffline to link to external documentation.

Processing Details: The javadoc command produces a complete document each run; it does not do incremental builds. It relies on the Java compiler to load declarations, builds a rich internal representation, and picks up user-supplied documentation from comments. It works on stub files without method bodies, allowing early documentation. It must be able to find all referenced classes (bootstrap, extension, user). See How Classes Are Found.

📦 JAVADOC DOCLETS

You can customize output with doclets. The built-in standard doclet generates HTML. Use -doclet to specify a custom doclet. The standard doclet adds its own set of options (see below).

📄 SOURCE FILES

The javadoc command uses Java source files (.java), package comment files, overview comment files, and unprocessed files (like images). Test and template files can be stored in the source tree but should be excluded from processing.

💻 CLASS SOURCE FILES

Each class/interface can have its own documentation comment in the source file.

📦 PACKAGE COMMENT FILES

Each package can have a documentation comment in package-info.java (preferred) or package.html. The comment is placed before the package declaration in package-info.java or within <body> in package.html. The javadoc command copies the comment between <body> and </body> (for package.html), processes tags, inserts the text at the bottom of the package summary page, and copies the first sentence to the top.

Example package-info.java:

/**
 * Provides the classes necessary to create an
 * applet and the classes an applet uses
 * to communicate with its applet context.
 * <p>
 * The applet framework involves two entities:
 * the applet and the applet context.
 * An applet is an embeddable window (see the
 * {@link java.awt.Panel} class) with a few extra
 * methods that the applet context can use to
 * initialize, start, and stop the applet.
 *
 * @since 1.0
 * @see java.awt
 */
package java.lang.applet;

📑 OVERVIEW COMMENT FILES

An overview comment file (e.g., overview.html) is placed anywhere; use the -overview option to specify it. The content is a big HTML comment. The first sentence becomes the summary at the top of the overview page. The processed text appears at the bottom. Only created when documenting two or more packages.

📁 UNPROCESSED FILES

Put extra files (images, examples) in a doc-files directory inside any package directory. The javadoc command copies the entire directory to the destination. Example link in a comment: <img src="doc-files/Button.gif">.

🧪 TEST AND TEMPLATE FILES

Test files (valid compilable sources) and template files (often .java but invalid) can be stored in subdirectories with invalid names (e.g., test-files/) to avoid processing. To document test files, run javadoc with explicit file names like com/package1/test-files/*.java.

📂 GENERATED FILES

The standard doclet generates HTML files organized as follows:

📄 BASIC CONTENT PAGES

🔗 CROSS-REFERENCE PAGES

🛠️ SUPPORT PAGES

🖼️ HTML FRAMES

Two or three frames are generated based on the number of packages. A single package yields only the class list frame. Two or more packages add a package list frame and an overview page.

📁 GENERATED FILE STRUCTURE

Class files are placed in a directory hierarchy mirroring the package structure. Example for java.applet with destination apidocs:

📜 GENERATED API DECLARATIONS

Each class, interface, field, constructor, and method description starts with a declaration. Modifiers shown: public, protected, private, abstract, final, static, transient, volatile. synchronized and native are not shown because they are implementation details.

📝 DOCUMENTATION COMMENTS

✍️ SOURCE CODE COMMENTS

A documentation comment starts with /** and ends with */. Leading asterisks on each line are ignored. The first sentence is used as the summary (copied to the member summary).

Example:

/**
 * This is the typical format of a simple documentation comment
 * that spans two lines.
 */

Placement: Immediately before class, interface, constructor, method, or field declarations. Do not put an import statement between the comment and the declaration.

Parts: Main description followed by a tag section (starting with the first block tag @).

Block tags (@tag) and inline tags ({@tag}) are supported. The text is written in HTML; use entities for < (&lt;), > (&gt;), and & (&amp;).

Multiple-field declarations: Only one documentation comment is allowed for a statement declaring multiple fields. To have individual comments, declare each field separately.

🧬 METHOD COMMENT INHERITANCE

Missing main description, @return, @param, or @throws tags are copied from the overridden method in the inheritance hierarchy. Use {@inheritDoc} to explicitly inherit a comment. Constructors, fields, and nested classes do not inherit comments.

🧬 CLASS AND INTERFACE INHERITANCE

Inheritance occurs when:

The javadoc command generates "Overrides" or "Specified by" subheadings with links.

🧮 METHOD COMMENTS ALGORITHM

If a method lacks a comment or has {@inheritDoc}, the search order is:

  1. Look in each directly implemented (or extended) interface in declaration order.
  2. If not found, recursively apply the algorithm to each interface.
  3. If still not found and this is a class (not an interface):
    1. Use the superclass's comment if available.
    2. Otherwise, recursively apply to the superclass.

🏷️ JAVADOC TAGS

Tags start with @ and are case-sensitive. They must appear at the beginning of a line (after optional asterisks). Block tags are placed in the tag section; inline tags can appear anywhere.

Custom tags are configured with the -tag option. See also How to Write Doc Comments.

📜 TAG DESCRIPTIONS

📍 WHERE TAGS CAN BE USED

The following tags can be used in all documentation comments: @see, @since, @deprecated, {@link}, {@linkplain}, {@docRoot}.

📖 OVERVIEW TAGS

In overview comment files: @see, @since, @serialField, @author, @version, {@link}, {@linkplain}, {@docRoot}.

📦 PACKAGE TAGS

In package.html or package-info.java: @see, @since, @serial (with include/exclude), @author, @version, {@link}, {@linkplain}, {@docRoot}.

🏷️ CLASS AND INTERFACE TAGS

In class/interface comments: @see, @since, @deprecated, @serial (with include/exclude), @author, @version, {@link}, {@linkplain}, {@docRoot}.

Example:

/**
 * A class representing a window on the screen.
 * For example:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  Sami Shaio
 * @version 1.13, 06/08/06
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow { ... }

🔢 FIELD TAGS

In field comments: @see, @since, @deprecated, @serial, @serialField, {@link}, {@linkplain}, {@docRoot}, {@value}.

🔧 CONSTRUCTOR AND METHOD TAGS

In constructor/method comments: @see, @since, @deprecated, @param, @return (not in constructors), @throws, @exception, @serialData (only for writeObject, readObject, writeExternal, readExternal, writeReplace, readResolve), {@link}, {@linkplain}, {@inheritDoc}, {@docRoot}.

Example:

/**
 * Returns the character at the specified index. An index
 * ranges from <code>0</code> to <code>length() - 1</code>
 *
 * @param     index the index of the desired character.
 * @return    the desired character.
 * @exception StringIndexOutOfRangeException
 *              if the index is not in the range <code>0</code>
 *              to <code>length()-1</code>
 * @see       java.lang.Character#charValue()
 */
public char charAt(int index) { ... }

⚙️ OPTIONS

The javadoc command uses doclets to determine output. The built-in standard doclet is used unless -doclet is specified. Options are case-insensitive except arguments.

Core options (available to all doclets): -bootclasspath, -breakiterator, -classpath, -doclet, -docletpath, -encoding, -exclude, -extdirs, -help, -locale, -overview, -package, -private, -protected, -public, -quiet, -source, -sourcepath, -subpackages, -verbose.

🔧 JAVADOC OPTIONS

📄 STANDARD DOCLET OPTIONS

📁 COMMAND-LINE ARGUMENT FILES

To shorten or simplify the command, you can use files containing arguments (except -J options). Argument files are referenced with @filename. Arguments can be space-separated or newline-separated. File names inside are relative to the current directory.

Example:

javadoc @options @packages

Options file example:

-d docs-filelist
-use
-splitindex
-windowtitle 'Java SE 7 API Specification'
-doctitle 'Java SE 7 API Specification'
-header '<b>Java™ SE 7</b>'
-bottom 'Copyright &copy; 1993-2011 Oracle and/or its affiliates. All rights reserved.'
-group "Core Packages" "java.*"
-overview /java/pubs/ws/1.7.0/src/share/classes/overview-core.html
-sourcepath /java/pubs/ws/1.7.0/src/share/classes

Packages file:

com.mypackage1
com.mypackage2
com.mypackage3

🏃 RUNNING THE JAVADOC COMMAND

Release number: javadoc -J-version. The standard doclet version appears in the output stream.

Call programmatically using com.sun.tools.javadoc.Main (reentrant). See The Standard Doclet.

📝 SIMPLE EXAMPLES

Document One or More Packages:

javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang

Change to root and run explicit packages:

cd /home/src/
javadoc -d /home/html java.awt java.awt.event

Run from any directory on explicit packages in one tree:

javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event

Document One or More Classes:

cd /home/src/java/awt
javadoc -d /home/html Button.java Canvas.java Graphics*.java

Document from root:

javadoc -d /home/html java/awt/Button.java java/applet/Applet.java

Document files from any directory:

javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java

Document Packages and Classes:

javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java

🌍 REAL-WORLD EXAMPLES

Command-line example (long command, better in an argument file):

javadoc -sourcepath /java/jdk/src/share/classes \
-overview /java/jdk/src/share/classes/overview.html \
-d /java/jdk/build/api \
-use \
-splitIndex \
-windowtitle 'Java Platform, Standard Edition 7 API Specification' \
-doctitle 'Java Platform, Standard Edition 7 API Specification' \
-header '<b>Java™ SE 7</b>' \
-bottom '<font size="-1"><a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.</font>' \
-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \
-group "Extension Packages" "javax.*" \
-J-Xmx180m \
@packages

Programmatic interface example:

import javax.tools.DocumentationTool;
import javax.tools.ToolProvider;

public class JavaAccessSample{
    public static void main(String[] args){
        DocumentationTool javadoc = ToolProvider.getSystemDocumentationTool();
        int rc = javadoc.run( null, null, null,
                 "-d", "/home/html",
                 "-sourcepath", "home/src",
                 "-subpackages", "java",
                 "-exclude", "java.net:java.lang",
                 "com.example");
    }
}

📦 THE MAKEFILE EXAMPLE

javadoc -sourcepath $(SRCDIR)              \   /* Sets path for source files   */
        -overview $(SRCDIR)/overview.html  \   /* Sets file for overview text  */
        -d /java/jdk/build/api             \   /* Sets destination directory   */
        -use                               \   /* Adds "Use" files             */
        -splitIndex                        \   /* Splits index A-Z             */
        -windowtitle $(WINDOWTITLE)        \   /* Adds a window title          */
        -doctitle $(DOCTITLE)              \   /* Adds a doc title             */
        -header $(HEADER)                  \   /* Adds running header text     */
        -bottom $(BOTTOM)                  \   /* Adds text at bottom          */
        -group $(GROUPCORE)                \   /* 1st subhead on overview page */
        -group $(GROUPEXT)                 \   /* 2nd subhead on overview page */
        -J-Xmx180m                         \   /* Sets memory to 180MB         */
        java.lang java.lang.reflect        \   /* Sets packages to document    */
        java.util java.io java.net         \
        java.applet
WINDOWTITLE = 'Java™ SE 7 API Specification'
DOCTITLE = 'Java™ Platform Standard Edition 7 API Specification'
HEADER = '<b>Java™ SE 7</font>'
BOTTOM = '<font size="-1">
      <a href="http://bugreport.sun.com/bugreport/">Submit a bug or feature</a><br/>
      Copyright &copy; 1993, 2011, Oracle and/or its affiliates. All rights reserved.<br/>
      Oracle is a registered trademark of Oracle Corporation and/or its affiliates.
      Other names may be trademarks of their respective owners.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"'
GROUPEXT  = '"Extension Packages" "javax.*"'
SRCDIR = '/java/jdk/1.7.0/src/share/classes'

📝 NOTES

🔧 GENERAL TROUBLESHOOTING

⚠️ ERRORS AND WARNINGS

Error and warning messages include the file name and line number of the declaration line. Example: error: cannot read: Class1.java means the file could not be loaded.

🌍 ENVIRONMENT

🔗 SEE ALSO

📚 RELATED DOCUMENTS

javadoc(1) □✕
📝 NAME 🚀 Quick Reference 📖 SYNOPSIS 📘 DESCRIPTION
🔄 PROCESS SOURCE FILES 📦 JAVADOC DOCLETS
📄 SOURCE FILES
💻 CLASS SOURCE FILES 📦 PACKAGE COMMENT FILES 📑 OVERVIEW COMMENT FILES 📁 UNPROCESSED FILES 🧪 TEST AND TEMPLATE FILES
📂 GENERATED FILES
📄 BASIC CONTENT PAGES 🔗 CROSS-REFERENCE PAGES 🛠️ SUPPORT PAGES 🖼️ HTML FRAMES 📁 GENERATED FILE STRUCTURE 📜 GENERATED API DECLARATIONS
📝 DOCUMENTATION COMMENTS
✍️ SOURCE CODE COMMENTS 🧬 METHOD COMMENT INHERITANCE 🧬 CLASS AND INTERFACE INHERITANCE 🧮 METHOD COMMENTS ALGORITHM
🏷️ JAVADOC TAGS
📜 TAG DESCRIPTIONS
📍 WHERE TAGS CAN BE USED
📖 OVERVIEW TAGS 📦 PACKAGE TAGS 🏷️ CLASS AND INTERFACE TAGS 🔢 FIELD TAGS 🔧 CONSTRUCTOR AND METHOD TAGS
⚙️ OPTIONS
🔧 JAVADOC OPTIONS 📄 STANDARD DOCLET OPTIONS
📁 COMMAND-LINE ARGUMENT FILES 🏃 RUNNING THE JAVADOC COMMAND
📝 SIMPLE EXAMPLES 🌍 REAL-WORLD EXAMPLES 📦 THE MAKEFILE EXAMPLE 📝 NOTES
🔧 GENERAL TROUBLESHOOTING ⚠️ ERRORS AND WARNINGS 🌍 ENVIRONMENT 🔗 SEE ALSO 📚 RELATED DOCUMENTS

Generated by phpman v4.9.29 · Markdown · JSON · MCP Author: Che Dong Under GNU General Public License
2026-07-21 05:57 @2600:1f28:365:80b0:e9a9:ac35:f5fe:ea62
CrawledBy CCBot/2.0 (https://commoncrawl.org/faq/)
Valid XHTML 1.0 Transitional!Valid CSS!
Enhanced by LLM: deepseek-v4-flash / taotoken.net / www.chedong.com - original format

^_top_^