Javadoc Command (original) (raw)

6/6

The javadoc command-line synopsis is javadoc [options] [packagenames] [sourcefiles] [@files]. The options can either be Doclet options or Standard Doclet options. The javadoc command can also be run programmatically.

Javadoc Doclets

You use the javadoc tool and its options to generate HTML pages of API documentation from Java source files.

Javadoc Doclet Options

The javadoc command has options for doclets. The Standard Doclet provides additional options.

The javadoc command uses doclets to determine its output and uses the default Standard Doclet unless a custom doclet is specified with the -doclet option. While option names are not case-sensitive, their arguments are. Options are described in the javadoc chapter of the Java Platform, Standard Edition Tools Reference.

Process Source Files

The javadoc command processes files that end in the source file extension and other files described in Source Files. If you run the javadoc command by passing in individual source file names, then you can determine exactly which source files are processed. However, that isn't how most developers want to work because it's simpler to pass in package names. The javadoc command can be run three ways, without explicitly specifying the source file names. You can pass in package names, use the -subpackages option, or use wild cards with source file names. In these cases, the javadoc command processes a source file only when the file fulfills all of the following requirements:

• The file name prefix (with .java removed) is a valid class name.
• The path name relative to the root of the source tree is a valid package name after the separators are converted to dots.
• The package statement contains the valid package name.

Processing Links

During a run, the javadoc command adds cross-reference links to package, class, and member names that are being documented as part of that run. Links appear in the following places:

• Declarations (return types, argument types, and field types)
• See Also sections that are generated from @see tags
• Inline text generated from {@link} tags
• Exception names generated from @throws tags
• Specified by links to interface members and Overrides links to class members
• Summary tables listing packages, classes, and members
• Package and class inheritance trees
• The index

Processing Details

The javadoc command produces one complete document every time it runs. It doesn't perform incremental builds that modify or directly incorporate the results from earlier runs. However, the javadoc command can link to results from other runs.

The javadoc command implementation requires and relies on the Java compiler. The javadoc command calls part of the javac command to compile the declarations and ignore the member implementations. The javadoc command builds a rich internal representation of the classes that includes the class hierarchy and use relationships to generate the HTML documentation. The javadoc command also picks up user-supplied documentation from documentation comments in the source code.

The javadoc command can run on source files that are pure stub files with no method bodies. This means that you can write documentation comments and run the javadoc command in the early stages of design before API implementation.

Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which may rely on implicit, rather than explicit, source code. For example, the javadoc command documents default constructors that are present in the compiled class files but not in the source code.

In many cases, the javadoc command lets you generate documentation for source files with incomplete or erroneous code. You can generate documentation before any debugging and troubleshooting is done. The javadoc command does primitive checking of documentation comments.

When the javadoc command builds its internal structure for the documentation, it loads all referenced classes. Because of this, the javadoc command must be able to find all referenced classes, and whether they're bootstrap classes, extensions, or user classes.

Javadoc Doclets

You can customize the content and format of the javadoc command output with doclets. The javadoc command has a default built-in doclet, called the Standard Doclet, that generates HTML-formatted API documentation. You can write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you want.

When a custom doclet isn't specified with the -doclet option, the javadoc command uses the default Standard Doclet. The javadoc command has several options that are available regardless of which doclet is being used. The Standard Doclet adds a supplementary set of command-line options.

Using the link Option

You use -link option to classes referenced to by your code, but not documented in the current javadoc command run.

For links to go to valid pages, you must know where those HTML pages are located and specify that location with the extdocURL option. This allows third-party documentation to link to Java. Omit the -link option when you want the javadoc command to create links only to APIs within the documentation it's generating in the current run. Without the -link option, the javadoc command doesn't create links to documentation for external references because it doesn't know whether or where that documentation exists. The -link option can create links in several places in the generated documentation. See Javadoc Doclets. Another use is for cross-links between sets of packages: Execute the javadoc command on one set of packages, then run the javadoc command again on another set of packages, creating links both ways between both sets.

Differences Between the -link and -linkoffline Options

Use the -link option in the following cases:

• When you use a relative path to the external API document.
• When you use an absolute URL to the external API document if your shell lets you open a connection to that URL for reading.

Use the -linkoffline option when you use an absolute URL to the external API document, if your shell doesn't allow a program to open a connection to that URL for reading. This can occur when you're behind a firewall and the document you want to link to is on the other side.

Example 3-1 Example of Using an Absolute Link to External Documents

Use the following command if you want to link to the java.lang, java.io and other Java platform packages.

javadoc -link https://docs.oracle.com/javase/8/docs/api/com.mypackage

The command generates documentation for the package com.mypackage with links to the Java SE packages. The generated documentation contains links to the Object class, for example, in the class trees. Other options, such as the -sourcepath and -d options, aren't shown.

Example 3-2 Example of Using a Relative Link to External Documents

• In this example, there are two packages with documents that are generated in different runs of the javadoc command, and those documents are separated by a relative path.
• The packages are com.apipackage, an API, and com.spipackage, a service provider Interface (SPI).
• You want the documentation to reside in docs/api/com/apipackage and docs/spi/com/spipackage.
• Assuming that the API package documentation is already generated, and that docs is the current directory, you document the SPI package with links to the API documentation by running: javadoc -d ./spi -link ../api com.spipackage.
  Note:
  The -link option is relative to the destination directory (docs/spi).

How to Reference a Class

For a link to an externally referenced class to appear (and not just its text label), the class must be referenced in a particular way. It isn't sufficient for the class to be referenced in the body of a method. It must be referenced in either of the following:import statement or in a declaration.

• In any kind of import statement. By wildcard import, import explicitly by name, or automatically import for java.lang.*.
• In a declaration: void mymethod(File f) {}.
  The reference can be in the return type or parameter type of a method, constructor, field, class, or interface, or in an implements, extends, or throws statement.
  When you use the -link option, there can be many links that unintentionally don't appear. The text would appear without being a link. You can detect such text by the warnings they emit. The simplest way to properly reference a class and add the link is to import that class.

In a declaration: void mymethod(File f) {}

Package List

The -link option requires that a file named package-list, which is generated by the javadoc command, exists at the URL that you specify with the -link option. In JDK 8, the package-list file is a simple text file that lists the names of packages documented at that location.

When javadoc is run without the -link option and encounters a name that belongs to an externally referenced class, it prints the name with no link. However, when the -link option is used, the javadoc command searches the package-list file at the specified extdocURL location for that package name. When it finds the package name, it prefixes the name with extdocURL.

For there to be no broken links, all of the documentation for the external references must exist at the specified URLs. The javadoc command does not check that these pages exist, but only that the package-list exists.

Multiple Links

You can supply multiple -link options to link to any number of externally generated documents. Specify a different link option for each external document to link to javadoc -link extdocURL1 -link extdocURL2 ... -link extdocURLn com.mypackage where extdocURL1, extdocURL2, ... extdocURLn point respectively to the roots of external documents, each of which contains a file named package-list.

Cross Linking

Note:

Bootstrapping might be required when cross-linking two or more documents that were previously generated. If the package-list file doesn't exist for either document when you run the javadoc command on the first document, then the package-list doesn't yet exist for the second document. Therefore, to create the external links, you must regenerate the first document after you generate the second document.

In this case, the purpose of first generating a document is to create its package-list (or you can create it by hand if you are certain of the package names). Then, generate the second document with its external links. The javadoc command prints a warning when a needed external package-list file doesn't exist.

Using the linkoffline Option

You use linkoffline option to link to the java.lang, java.io and other Java SE packages

Absolute Links to External Documents

You might have a situation where you want to link to the java.lang, java.io and other Java SE packages. However, your shell doesn't have web access. In this case, do the following:

1. Open the package-list file in a browser at API Specification.
2. Save the file to a local directory, and point to this local copy with the second argument, packagelistLoc. In this example, the package list file was saved to the current directory.

The following command generates documentation for the package com.mypackage with links to the Java SE packages. The generated documentation contains links to the Object class, for example, in the class trees. Other necessary options, such as -sourcepath, aren't shown.

javadoc -linkoffline https://docs.oracle.com/javase/8/docs/api/.com.mypackage

Relative Links to External Documents

It's not very common to use -linkoffline with relative paths, for the simple reason that the -link option is usually enough. When you use the -linkoffline option, the package-list file is usually local, and when you use relative links, the file you're linking to is also local, so it's usually unnecessary to give a different path for the two arguments to the -linkoffline option. When the two arguments are identical, you can use the -link option.

Create a package-list File Manually

If a package-list file doesn't exist yet, but you know what package names your document will link to, then you can manually create your own copy of this file and specify its path with packagelistLoc. An example would be where the package-list file for com.spipackage didn't exist when com.apipackage package was first generated. This technique is useful when you need to generate documentation that links to new external documentation whose package names you know, but which isn't yet published. Similarly, two companies can share their unpublished package-list files so they can release their cross-linked documentation simultaneously.

Link to Multiple Documents

You can include the -linkoffline option once for each generated document that you want to refer to:

javadoc -linkoffline extdocURL1 packagelistLoc1 -linkoffline extdocURL2 packagelistLoc2 ...

Update Documents

You can also use the -linkoffline option when your project has dozens or hundreds of packages. If you've already run the javadoc command on the entire source tree, then you can quickly make small changes to documentation comments and rerun the javadoc command on a portion of the source tree. Be aware that the second run works properly only when your changes are to documentation comments and not to declarations. If you were to add, remove, or change any declarations from the source code, then broken links could show up in the index, package tree, inherited member lists, Use page, and other places.

First, create a new destination directory, such as update, for this new small run. In this example, the original destination directory is named html. In the simplest example, change the directory to the parent of html. Set the first argument of the -linkoffline option to the current directory and set the second argument to the relative path to html, where it can find the package-list file and pass in only the package names of the packages that you want to update:

javadoc -d update -linkoffline . html com.mypackage

Oracle Solaris, Linux, and macOS: When the javadoc command completes, copy these generated class pages in update/com/package (not the overview or index) to the original files in the html/com/package.

Windows: When the javadoc command completes, copy these generated class pages in update\com\package (not the overview or index) to the original files in html\com\package.

Using the Tag Option

Use Xaoptcmf arguments to determine where in the source code the tag is allowed to be placed, and whether the tag can be disabled (using X).

Placement of Tags

You can supply either a, to allow the tag in all places, or any combination of the other letters:

• X (disable tag)
• a (all)
• o (overview)
• p (packages)
• t (types, that is classes and interfaces)
• c (constructors)
• m (methods)
• f (fields)
• s (modules)

Examples of Single Tags

An example of a tag option for a tag that can be used anywhere in the source code is: -tag todo:a:"To Do:".

If you want the @todo tag to be used only with constructors, methods, and fields, then you use: -tag todo:cmf:"To Do:".

Notice the last colon (:) isn't a parameter separator, but is part of the heading text. You can use either tag option for source code that contains the @todo tag, such as: @todo The documentation for this method needs work.

Colons in Tag Names

Use a backslash to escape a colon that you want to use in a tag name. Use the -tag ejb\\:bean:a:"EJB Bean:" option for the following documentation comment:

/**

• @ejb:bean */

Spell-Checking Tag Names

Some developers put custom tags in the source code that they don't always want to produce as output. In these cases, it's important to list all tags that are in the source code, enabling the ones you want to output and disabling the ones you don't want to output. The presence of X disables the tag, while its absence enables the tag. This gives the javadoc command enough information to know whether a tag it encounters is unknown, which is probably the results of a typographical error or a misspelling. The javadoc command prints a warning in these cases. You can add X to the placement values already present, so that when you want to enable the tag, you can simply delete the X. For example, if the @todo tag is a tag that you want to suppress on output, then you would use: -tag todo:Xcmf:"To Do:". If you would rather keep it simple, then use this: -tag todo:X. The syntax -tag todo:X works even when the @todo tag is defined by a taglet.

Order of Tags

The order of the -tag and -taglet options determines the order that the tags are produced. You can mix the custom tags with the standard tags to intersperse them. The tag options for standard tags are placeholders only for determining the order. They take only the standard tag's name. Subheadings for standard tags can't be altered. For example, if the -tag option is missing, then the position of the -taglet option determines its order. If they're both present, then whichever appears last on the command line determines its order. This happens because the tags and taglets are processed in the order that they appear on the command line. For example, if the -taglet and -tag options have the name todo value, then the one that appears last on the command line determines the order.

Example of a Complete Set of Tags

This example inserts To Do after Parameters and before Throws in the output. By using X, it also specifies that the @example tag might be encountered in the source code that shouldn't be displayed during this run. If you use @argfile on the command line to specify a file containing options, then you can put the tags on separate lines in an argument file similar to this (no line continuation characters needed):

-tag param -tag return -tag todo:a:"To Do:" -tag throws -tag see -tag example:X

When the javadoc command parses the documentation comments, any tag encountered that's neither a standard tag nor passed in with the -tag or -taglet options is considered unknown, and a warning is thrown.

The standard tags are initially stored internally in a list in their default order. Whenever the -tag options are used, those tags get appended to this list. Standard tags are moved from their default position. Therefore, if a -tag option is omitted for a standard tag, then it remains in its default position.

Avoiding Conflicts

If you want to create your own namespace, then you can use a dot-separated naming convention similar to that used for packages: com.mycompany.todo. Oracle continues to create standard tags whose names don't contain dots. Any tag that you create overrides the behavior of a tag by the same name defined by Oracle. If you create a @todo tag or taglet, then it always has the same behavior that you define, even when Oracle later creates a standard tag of the same name.

Annotations Versus Javadoc Tags

In general, if the markup that you want to add is intended to affect or produce documentation, then it should be a Javadoc tag. Otherwise, it should be an annotation. See Custom Tags and Annotations in How to Write Doc Comments for the Javadoc Tool.

You can also create more complex block tags or custom inline tags with the -taglet option.

javadoc Command-Line Argument Files

To shorten or simplify the javadoc command, you specify one or more files that contain arguments to the javadoc command (except -J options). This lets you to create javadoc commands of any length on any operating system.

When you run the javadoc command, pass the path and name of each argument file with the @ leading character. When the javadoc command encounters an argument beginning with the @ character, it expands the contents of that file into the argument list.

Examples

Single Argument File

You can use a single argument file named argfile to hold all javadoc command arguments: javadoc @argfile.

Two Argument Files

The argument file contains the contents of both files. You can create two argument files: One for the javadoc command options and the other for the package names or source file names. Notice the following lists have no line-continuation characters.

Create a file named options that contains:

Oracle Solaris, Linux, and macOS:

-d docs-filelist -use -splitindex -windowtitle 'Javadoc' -doctitle 'Javadoc Guide' -header 'Java™ SE ' -bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.' -group "Core Packages" "java.*" -overview /java/jdk9/docs/api/overview-summary -sourcepath /java/

Windows:

-d docs-filelist -use -splitindex -windowtitle 'Javadoc' -doctitle 'Javadoc Guide' -header 'Java™ SE 7' -bottom 'Copyright © 1993-2011 Oracle and/or its affiliates. All rights reserved.' -group "Core Packages" "java.*" -overview \java\jdk9\docs\api\overview-summary.html -sourcepath \java\

Create a file named packages that contains:

com.mypackage1 com.mypackage2 com.mypackage3

Run the javadoc command as follows:

javadoc @options @packages

Argument Files with Paths

The argument files can have paths, but any file names inside the files are relative to the current working directory (not path1 or path2):

Oracle Solaris, Linux, and macOS:

javadoc @path1/options @path2/packages

Windows:

javadoc @path1\options @path2\packages

Option Arguments

The following example saves an argument to a javadoc command option in an argument file. The -bottom option is used because it can have a lengthy argument. You can create a file named bottom to contain the text argument:

Run the javadoc command as follows: javadoc -bottom @bottom @packages.

You can also include the -bottom option at the start of the argument file and run the javadoc command as follows: javadoc @bottom @packages.

The Standard Doclet

The Standard Doclet is the doclet provided by Oracle that produces Javadoc's default HTML-formatted API output.

This topic contains the following sections:

• Javadoc Standard Doclet
• Generated Files

Javadoc Standard Doclet

Javadoc uses the Standard Doclet if no other doclet is specified using the Javadoc's -doclet option on the command line. In JDK 9, the Doclet API has been updated to use newer, more powerful APIs, that can better represent all the recent new language features. The Standard Doclet is updated to use this Doclet API.

The Standard Doclet is the doclet provided by Oracle that produces Javadoc's default HTML-formatted API output. The API Specification for the Java platform in this JDK documentation is an example of the Standard Doclet's output.

Standard doclet options are described in the javadoc section of the Java Platform, Standard Edition Tools Reference.

The -group name p1:p2 groups specified packages together in overview page.

The -group groupheading packagepattern:packagepattern separates packages on the overview page into whatever groups you specify, one group per table. You specify each group with a different -group option. The groups appear on the page in the order specified on the command line. Packages are alphabetized within a group. For a specified -group option, the packages matching the list of packagepattern expressions appear in a table with the heading groupheading.

• The groupheading value can be any text and can include white space. This text is placed in the table heading for the group.
• The packagepattern value can be any package name at the start of any package name followed by an asterisk (*). The asterisk is the only wildcard allowed and means match any characters. Multiple patterns can be included in a group by separating them with colons (:). If you use an asterisk in a pattern or pattern list, then the pattern list must be inside quotation marks, such as "java.lang*:java.util".

When you don't supply a -group option, all packages are placed in one group with the heading Packages and appropriate subheadings. If the subheadings don't include all documented packages (all groups), then the remaining packages appear in a separate group with the subheading Other Packages.

For example, the following javadoc command separates the three documented packages into Core, Extension, and Other Packages. The trailing dot (.) doesn't appear in java.lang*. Including the dot, such as java.lang.* omits the java.lang package.

javadoc -group "Core Packages" "java.lang*:java.util" -group "Extension Packages" "javax.*" java.lang java.lang.reflect java.util javax.servlet java.new

Core Packages

java.lang

java.lang.reflect

java.util

Extension Packages

javax.servlet

Other Packages

java.new

Generated Files

You use the javadoc command as a Standard Doclet that generates HTML-formatted documentation.

The Standard Doclet generates the basic content, cross-reference, and support pages. Each HTML page corresponds to a separate file. The javadoc command generates two types of files. The first type is named after classes and interfaces. The second type contains hyphens (such as package-summary.html) to prevent conflicts with the first type of file.

Basic Content Pages

• One class or interface page (classname.html) for each class or interface being documented.
• One package page (package-summary.html) for each package being documented. The javadoc command includes any HTML text provided in a file with the name package.html or package-info.java in the package directory of the source tree.
• One overview page (overview-summary.html) for the entire set of packages. The overview page is the front page of the generated document. The javadoc command includes any HTML text provided in a file specified by the -overview option. The overview page is created only when you pass two or more package names into the javadoc command. See HTML Frames and Javadoc Doclet Options.

Cross-Reference Pages

• One class hierarchy page for the entire set of packages (overview-tree.html). To view the hierarchy page, click Overview in the navigation bar and click Tree.
• One class hierarchy page for each package (package-tree.html). To view the hierarchy page, go to a particular package, class, or interface page, and click Tree to display the hierarchy for that package.
• One Use page for each package (package-use.html) and a separate Use page for each class and interface (class-use/classname.html). The Use page describes what packages, classes, methods, constructors and fields use any part of the specified class, interface, or package. For example, given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. To view the Use page, go to the package, class, or interface and click the Use link in the navigation bar.
• A deprecated API page (deprecated-list.html) that lists all deprecated APIs and their suggested replacements. Avoid deprecated APIs because they can be removed in future implementations.
  A constant field values page (constant-values.html) for the values of static fields.
• A serialized form page (serialized-form.html) that provides information about serializable and externalizable classes with field and method descriptions. The information on this page is of interest to reimplementors, and not to developers who want to use the API. To access the serialized form page, go to any serialized class and click Serialized Form in the See Also section of the class comment. The Standard Doclet generates a serialized form page that lists any class (public or non-public) that implements Serializable with its readObject and writeObject methods, the fields that are serialized, and the documentation comments from the @serial, @serialField, and @serialData tags. Public Serializable classes can be excluded by marking them (or their package) with @serial exclude , and package-private Serializable classes can be included by marking them (or their package) with an @serial include . You can generate the complete serialized form for public and private classes by running the javadoc command without specifying the -private option. See Javadoc Doclet Options.
• An index page (index-*.html) of all class, interface, constructor, field and method names, in alphabetical order. The index page is internationalized for Unicode and can be generated as a single file or as a separate file for each starting character (such as A–Z for English).

Support Pages

• A help page (help-doc.html) that describes the navigation bar and the previous pages. Use -helpfile to override the default help file with your own custom help file.
• One index.html file that creates the HTML frames for display. Load this file to display the front page with frames. The index.html file contains no text content.
• Several frame files (*-frame.html) that contains lists of packages, classes, and interfaces. The frame files display the HTML frames.
• A package-list file that is used by the -link and -linkoffline options. The package list file is a text file that is not reachable through links.
• A style sheet file (stylesheet.css) that controls a limited amount of color, font family, font size, font style, and positioning information on the generated pages.
• A doc-files directory that holds image, example, source code, or other files that you want copied to the destination directory. These files aren't processed by the javadoc command. This directory is not processed unless it exists in the source tree.

See Javadoc Doclet Options.

HTML Frames

The javadoc command generates the minimum number of frames necessary (two or three) based on the values passed to the command. It omits the list of packages when you pass a single package name or source files that belong to a single package as an argument to the javadoc command. Instead, the javadoc command creates one frame in the left-hand column that displays the list of classes. When you pass two or more package names, the javadoc command creates a third frame that lists all packages and an overview page (overview-summary.html). The HTML frames are enabled by default, but can be disabled by the --no-frames option. To bypass frames, click the No Frames link or enter the page set from the overview-summary.html page. The Javadoc Search feature provides a better way to navigate and saves screen space.

Generated File Structure

The generated class and interface files are organized in the same directory hierarchy that Java source files and class files are organized. This structure is one directory per subpackage.

Oracle Solaris, Linux, and macOS: For example, the document generated for the java.math.BigDecimal class would be located at java/math/BigDecimal.html.

Windows: For example, the document generated for the java.math.BigDecimal class would be located at java\math\BigDecimal.html.

The file structure for the java.math package follows, assuming that the destination directory is named apidocs. All files that contain the word frame appear in the upper-left or lower-left frames, as noted. All other HTML files appear in the right-hand frame.

Directories are bold. The asterisks (*) indicate the files and directories that are omitted when the arguments to the javadoc command are source file names rather than package names. When arguments are source file names, an empty package list is created. The doc-files directory isn't created in the destination unless it exists in the source tree.

Generated API Declarations

The javadoc command generates a declaration at the start of each class, interface, field, constructor, and method description for that API item. For example, the declaration for the Boolean class is:

public final class Boolean extends Object implements Serializable

The declaration for the Boolean.valueOf method is:

public static Boolean valueOf(String s)

The javadoc command can include the modifiers public, protected, private, abstract, final, static, transient, and volatile, but not synchronized or native. The synchronized and native modifiers are considered implementation detail and not part of the API specification.

Rather than relying on the keyword synchronized, APIs should document their concurrency semantics in the main description of the comment. For example, a description might be:

A single enumeration cannot be used by multiple threads concurrently.

The document shouldn't describe how to achieve these semantics. As another example, while the Hashtable option should be thread-safe, there is no reason to specify that it's achieved by synchronizing all of its exported methods. It’s better to reserve the right to synchronize internally for higher concurrency.

Examples of Running the javadoc Command

You can run the javadoc command on entire packages or individual source files. Use the public programmatic interface to call the javadoc command from within programs written in the Java language.

The release number of the javadoc command can be determined with the javadoc -J-version option. The release number of the Standard Doclet appears in the output stream. It can be turned off with the -quiet option.

Use the public programmatic interface in com.sun.tools.javadoc.Main (and the javadoc command is reentrant) to call the javadoc command from within programs written in the Java language.

The following instructions call the Standard HTML Doclet. To call a custom doclet, use the -doclet and -docletpath options.

Simple Examples

The following are simple examples of running the javadoc command on entire packages or individual source files. Each package name has a corresponding directory name.

Oracle Solaris, Linux, and macOS: In the following examples, the source files are located at /home/src/java/awt/*.java. The destination directory is /home/html.

Windows: In the following examples, the source files are located at C:\home\src\java\awt\*java. The destination directory is C:\home\html.

Document One or More Packages: To document a package, the source files for that package must be located in a directory that has the same name as the package.

Oracle Solaris, Linux, and macOS:

• If a package name has several identifiers (separated by dots, such as java.awt.color), then each subsequent identifier must correspond to a deeper subdirectory (such as java/awt/color).
• You can split the source files for a single package among two such directory trees located at different places, as long as the -sourcepath option points to them both. For example, src1/java/awt/color and src2/java/awt/color.

Windows:

• If a package name has several identifiers (separated by dots, such as java.awt.color), then each subsequent identifier must correspond to a deeper subdirectory (such as java\awt\color).
• You can split the source files for a single package among two such directory trees located at different places, as long as the -sourcepath option points to them both. For example, src1\java\awt\color and src2\java\awt\color.

You can run the javadoc command either by changing directories (with the cd command) or by using the -sourcepath option. The following examples illustrate both alternatives:

Example 1 Recursive Run from One or More Packages

This example uses -sourcepath so the javadoc command can be run from any directory for recursion. It traverses the subpackages of the Java directory excluding packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a subpackage of java.lang. To also traverse down other package trees, append their names to the -subpackages argument, such as java:javax:org.xml.sax.

javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude

Example 2 Change to Root and Run Explicit Packages

1. Change to the parent directory of the fully qualified package.
2. Run the javadoc command with the names of one or more packages that you want to document:
   Oracle Solaris, Linux, and macOS:
   cd /home/src/
   javadoc -d /home/html java.awt java.awt.event
   Windows:
   cd C:\home\src\
   javadoc -d C:\home\html java.awt java.awt.event
   To also traverse down other package trees, append their names to the -subpackages argument, such as java:javax:org.xml.sax.

Example 3 Run from Any Directory on Explicit Packages in One Tree

In this case, it doesn't matter what the current directory is. Run the javadoc command and use the -sourcepath option with the parent directory of the top-level package. Provide the names of one or more packages that you want to document:

Oracle Solaris, Linux, and macOS:

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

Windows:

javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event

Example 4 Run from Any Directory on Explicit Packages in Multiple Trees

Run the javadoc command and use the -sourcepath option with a colon-separated list of the paths to each tree's root. Provide the names of one or more packages that you want to document. All source files for a specified package don't need to be located under a single root directory, but they must be found somewhere along the source path.

Oracle Solaris, Linux, and macOS:

javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event

Windows:

javadoc -d C:\home\html -sourcepath C:\home\src1;C:\home\src2 java.awt java.awt.event

The result is that all cases generate HTML-formatted documentation for the public and protected classes and interfaces in packages java.awt and java.awt.event and save the HTML files in the specified destination directory. Because two or more packages are being generated, the document has three HTML frames: one for the list of packages, another for the list of classes, and the third for the main class pages.

Document One or More Classes

The second way to run the javadoc command is to pass one or more source files. You can run javadoc either of the following two ways: by changing directories (with the cd command) or by fully specifying the path to the source files. Relative paths are relative to the current directory. The -sourcepath option is ignored when passing source files. You can use command-line wildcards, such as an asterisk (*), to specify groups of classes.

Example 1 Change to the Source Directory

Change to the directory that holds the source files. Then run the javadoc command with the names of one or more source files, you want to document.

This example generates HTML-formatted documentation for the classes Button, Canvas, and classes that begin with Graphics. Because source files rather than package names were passed in as arguments to the javadoc command, the document has two frames: one for the list of classes and the other for the main page.

Oracle Solaris, Linux, and macOS:

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

Windows:

cd C:\home\src\java\awt javadoc -d C:\home\html Button.java Canvas.java Graphics*.java

Example 2 Change to the Root Directory of the Package

This is useful for documenting individual source files from different subpackages off of the same root. Change to the package root directory, and specify the source files with paths from the root.

Oracle Solaris, Linux, and macOS:

cd /home/src/ javadoc -d /home/html java/awt/Button.java java/math/BigDecimal.java

Windows:

cd C:\home\src javadoc -d \home\html java\awt\Button.java java\math\BigDecimal.java

Example 3 Document Files from Any Directory

In this case, it doesn't matter what the current directory is. Run the javadoc command with the absolute path (or path relative to the current directory) to the source files that you want to document.

Oracle Solaris, Linux, and macOS:

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

Windows:

javadoc -d C:\home\html C:\home\src\java\awt\Button.java ^ C:\home\src\java\awt\Graphics*.java

Document Packages and Classes

You can document entire packages and individual classes at the same time. The following is an example that mixes two of the previous examples. You can use the -sourcepath option for the path to the packages but not for the path to the individual classes.

Example 1

Oracle Solaris, Linux, and macOS:

avadoc -d /home/html -sourcepath /home/src java.awt
/home/src/java/math/BigDecimal.java

Example 2

Windows:

javadoc -d C:\home\html -sourcepath C:\home\src java.awt ^ C:\home\src\java\math\BigDecimal.java

Notes

• If you omit the -windowtitle option, then the javadoc command copies the document title to the window title. The -windowtitle option text is similar to the -doctitle option, but without HTML tags to prevent those tags from appearing as just characters (plain text) in the window title.
• If you omit the -footer option, then the javadoc command copies the header text to the footer.
• Other important options you might want to use, but weren't needed in the previous example, are the -classpath and -link options.
• The javadoc command reads only files that contain valid class names. If the javadoc command isn't correctly reading the contents of a file, then verify that the class names are valid.