Name

javadoc - generate HTML pages of API documentation from Java sourcefiles

Synopsis

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

options

Specifies command-line options, separated by spaces. SeeStandardjavadocOptions,ExtrajavadocOptions,Standard Options forthe Standard Doclet, andExtra Options for theStandard Doclet.

packagenames

Specifies names of packages that you want to document, separated byspaces, for examplejava.lang java.lang.reflect java.awt.If you want to also document the subpackages, then use the-subpackages option to specify the packages.

By default,javadoc looks for the specified packages inthe current directory and subdirectories. Use the-sourcepath option to specify the list of directories whereto look for packages.

sourcefiles

Specifies names of Java source files that you want to document,separated by spaces, for exampleClass.java Object.java Button.java. By default,javadoc looks for the specified classes in the currentdirectory. However, you can specify the full path to the class file anduse wildcard characters, for example/home/src/java/awt/Graphics*.java. You can also specify thepath relative to the current directory.

@files

Specifies names of files that contain a list ofjavadoctool options, package names, and source file names in any order.

Description

Thejavadoc tool parses the declarations anddocumentation comments in a set of Java source files and processes themusing a pluggable back-end called adoclet.

Thestandarddoclet is the one that is used by default, and can producecorresponding HTML pages that describe the public and protected classes,nested and implicitly declared classes (but not anonymous innerclasses), interfaces, constructors, methods, and fields. The standarddoclet interprets the content of documentation comments according to theJavaDoc Documentation CommentSpecification for the Standard Doclet. Custom tags in documentationcomments are supported by means oftaglets.

You can use thejavadoc tool and the standard doclet togenerate the API documentation or the implementation documentation for aset of source files.

You can run thejavadoc tool on entire packages,individual source files, or both. When documenting entire packages, youcan use the-subpackages option either to recursivelytraverse a directory and its subdirectories, or to pass in an explicitlist of package names. When you document individual source files, passin a list of Java source file names.

Documentation Comments

Thejavadoc tool uses the documentation comment, if any,that immediately precedes the beginning of the declaration, whether thatis an annotation, modifier, or the name being declared. If there aremultiple documentation comments before the declaration, only the lastone (closest to the declaration) will be used. If there are anydocumentation comments after the beginning of the declaration, they willbe ignored. To check for any extra or misplaced documentation comments,compile your source code with thejavac option-Xlint, or more specifically,-Xlint:dangling-doc-comments. Within a source file, you maysuppress any warnings generated by these options by using@SuppressWarnings("dangling-doc-comments") on a suitableenclosing declaration.

Conformance

The standard doclet does not validate the content of documentationcomments for conformance, nor does it attempt to correct any errors indocumentation comments. Anyone running javadoc is advised to be aware ofthe problems that may arise when generating non-conformant output oroutput containing executable content, such as JavaScript. The standarddoclet does provide theDocLint feature to helpdevelopers detect common problems in documentation comments; but it isalso recommended to check the generated output with any appropriateconformance and other checking tools.

For more details on the conformance requirements for HTML5 documents,seeConformancerequirements for authors in the HTML5 Specification. For moredetails on security issues related to web pages, see theOpen Web Application Security Project(OWASP) page.

Options

javadoc supports command-line options for both the mainjavadoc tool and the currently selected doclet. Thestandard doclet is used if no other doclet is specified.

GNU-style options (that is, those beginning with--) canuse an equal sign (=) instead of whitespace characters toseparate the name of an option from its value.

StandardjavadocOptions

The following corejavadoc options are equivalent tocorrespondingjavac options. SeeStandard Optionsinjavac for the detailed descriptions of usingthese options:

• --add-modules
• -bootclasspath
• --class-path,-classpath, or-cp
• --disable-line-doc-comments
• --enable-preview
• -encoding
• -extdirs
• --limit-modules
• --module
• --module-path or-p
• --module-source-path
• --release
• --source or-source
• --source-path or-sourcepath
• --system
• --upgrade-module-path

The following options are the corejavadoc options thatare not equivalent to a correspondingjavac option:

-breakiterator

Computes the first sentence of the description in a documentationcomment using an instance ofjava.text.BreakIterator todetectsentence breaks. The rules that are used depend on thecurrent locale: for example, for English, asentence break occurs after a period, question mark, or exclamationpoint followed by a space when the next word starts with a capitalletter. (This is meant to handle most abbreviations, such as "The serialno. is valid", but will not handle "Mr. Smith".)

The option is enabled by default if the language of the currentlocale is not English. If the language of the current locale is English,and the-breakiterator option is not given, a simpledefault algorithm is used, which just looks for a period followed by aspace.

In a traditional/**...*/ comment, the search for theend of the first sentence is terminated by an HTML block tag, such as<p>,<pre>, or the tag for aheading.

In a Markdown/// comment, the search for the end of thefirst sentence skips over any characters enclosed in code spans andlinks, and is terminated by the end of the initial block, as indicatedby a blank line or the beginning of the next block, such as a list,thematic break, or an HTML block.

The first sentence of the description in a documentation comment isused in summary tables, index pages, and other situations where a shortsummary is required. For more explicit control in any individualdocumentation comment, enclose the contents of the first sentence in a{@summary ...} tag, or when applicable, in a{@return ...} tag.

-docletclass

Generates output by using an alternate doclet. Use the fully qualifiedname. This doclet defines the content and formats the output. If the-doclet option isn't used, then thejavadoctool uses the standard doclet for generating the default HTML format.This class must implement thejdk.javadoc.doclet.Docletinterface. The path to this class is defined by the-docletpath option.

-docletpathpath

Specifies where to find doclet class files (specified with the-doclet option) and any JAR files it depends on. If thestarting class file is in a JAR file, then this option specifies thepath to that JAR file. You can specify an absolute path or a pathrelative to the current directory. Ifpath containsmultiple paths or JAR files, then they should be separated with a colon(:) on Linux and macOS, and a semicolon (;) onWindows. This option isn't necessary when thedocletstarting class is already in the search path.

-excludepkglist

Unconditionally, excludes the specified packages and theirsubpackages from the list formed by-subpackages. Itexcludes those packages even when they would otherwise be included bysome earlier or later-subpackages option.

The following example would includejava.io,java.util, andjava.math (among others), butwould exclude packages rooted atjava.net andjava.lang. Notice that these examples excludejava.lang.ref, which is a subpackage ofjava.lang. Arguments are separated by colons on alloperating systems.

• Linux and macOS:

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

• Windows:

  javadoc -sourcepath \user\src -subpackages java -exclude java.net:java.lang

--expand-requires(transitive|all)

Instructs the javadoc tool to expand the set of modules to bedocumented. By default, only the modules given explicitly on the commandline are documented. Supports the following values:

• transitive: additionally includes all the requiredtransitive dependencies of those modules.

• all: includes all dependencies.

--help,-help,-h, or-?

Prints a synopsis of the standard options.

--help-extra or-X

Prints a synopsis of the set of extra options.

-Jflag

Passesflag directly to the Java Runtime Environment (JRE)that runs thejavadoc tool. For example, if you must ensurethat the system sets aside 32 MB of memory in which to process thegenerated documentation, then you would call the-Xmxoption as follows:javadoc -J-Xmx32m -J-Xms32m com.mypackage. Be aware that-Xms is optional because it only sets the size of initialmemory, which is useful when you know the minimum amount of memoryrequired.

There is no space between theJ and theflag.

Use the-version option to report the version of the JREbeing used to run thejavadoc tool.

javadoc -J-versionjava version "17" 2021-09-14 LTSJava(TM) SE Runtime Environment (build 17+35-LTS-2724)Java HotSpot(TM) 64-Bit Server VM (build 17+35-LTS-2724, mixed mode, sharing)

-localename

Specifies the locale that thejavadoc tool uses when itgenerates documentation. The argument is the name of the locale, asdescribed injava.util.Locale documentation, such asen_US (English, United States) oren_US_WIN(Windows variant).

Specifying a locale causes thejavadoc tool to choosethe resource files of that locale for messages such as strings in thenavigation bar, headings for lists and tables, help file contents,comments in thestylesheet.css file, and so on. It alsospecifies the sorting order for lists sorted alphabetically, and thesentence separator to determine the end of the first sentence. The-locale option doesn't determine the locale of thedocumentation comment text specified in the source files of thedocumented classes.

-package

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

-private

Shows all classes and members.

-protected

Shows only protected and public classes and members. This is thedefault.

-public

Shows only the public classes and members.

-quiet

Shuts off messages so that only the warnings and errors appear to makethem easier to view. It also suppresses theversion string.

--show-membersvalue

Specifies which members (fields, methods, or constructors) aredocumented, wherevalue can be any of the following:

• public --- shows only public members
• protected --- shows public and protected members; thisis the default
• package --- shows public, protected, and packagemembers
• private --- shows all members

--show-module-contentsvalue

Specifies the documentation granularity of module declarations, wherevalue can beapi orall.

--show-packagesvalue

Specifies which module packages are documented, wherevalue canbeexported orall packages.

--show-typesvalue

Specifies which types (classes, interfaces, etc.) are documented,wherevalue can be any of the following:

• public --- shows only public types
• protected --- shows public and protected types; this isthe default
• package --- shows public, protected, and packagetypes
• private --- shows all types

-subpackagessubpkglist

Generates documentation from source files in the specified packagesand recursively in their subpackages. This option is useful when addingnew subpackages to the source code because they are automaticallyincluded. Each package argument is any top-level subpackage (such asjava) or fully qualified package (such asjavax.swing) that doesn't need to contain source files.Arguments are separated by colons on all operating systems. Wild cardsaren't allowed. Use-sourcepath to specify where to findthe packages. This option doesn't process source files that are in thesource tree but don't belong to the packages.

For example, the following commands generates documentation forpackages namedjava andjavax.swing and all oftheir subpackages.

• Linux and macOS:

  javadoc -d docs -sourcepath /home/user/src -subpackages java:javax.swing

• Windows:

  javadoc -d docs -sourcepath \user\src -subpackages java:javax.swing

-verbose

Provides more detailed messages while thejavadoc toolruns. Without the-verbose option, messages appear forloading the source files, generating the documentation (one message persource file), and sorting. The-verbose option causes theprinting of additional messages that specify the number of millisecondsto parse each Java source file.

--version

Prints version information.

-Werror

Reports an error if any warnings occur.

Note that if a Java source file contains an implicitly declaredclass, then that class and its public, protected, and package memberswill be documented regardless of the options such as--show-types,--show-members,-private,-protected,-package,and-public. If--show-members is specifiedwith valueprivate or if-private is used thenall private members of an implicitly declared class will be documentedtoo.

Extrajavadoc Options

Note: The additional options forjavadoc aresubject to change without notice.

The following additionaljavadoc options are equivalentto correspondingjavac options. SeeExtra Optionsinjavac for the detailed descriptions of usingthese options:

• --add-exports
• --add-reads
• --patch-module
• -Xmaxerrs
• -Xmaxwarns

Standard Options forthe Standard Doclet

The following options are provided by the standard doclet.

--add-scriptfile

Addsfile as an additional JavaScript file to the generateddocumentation. This option can be used one or more times to specifyadditional script files.

Command-line example:

javadoc --add-script first_script.js --add-script second_script.js pkg_foo

--add-stylesheetfile

Addsfile as an additional stylesheet file to the generateddocumentation. This option can be used one or more times to specifyadditional stylesheets included in the documentation.

Command-line example:

javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2.css pkg_foo

--allow-script-in-comments

Allow JavaScript in documentation comments, and options whose value ishtml-code.

-author

Includes the text of anyauthor tags in the generateddocumentation.

-bottomhtml-code

Specifies the text to be placed at the bottom of each generated page.The text can contain HTML tags and white space, but when it does, thetext must be enclosed in quotation marks. Use escape characters for anyinternal quotation marks within text.

-charsetname

Specifies the HTML character set for this document. The name shouldbe a preferred MIME name as specified in theIANA Registry,Character Sets.

For example:

javadoc -charset "iso-8859-1" mypackage

This command inserts the following line, containing ametaelement in the head of every generated page:

<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">

-ddirectory

Specifies the destination directory where thejavadoctool saves the generated HTML files. If you omit the-doption, then the files are saved to the current directory. Thedirectory value can be absolute or relative to the currentworking directory. The destination directory is automatically createdwhen thejavadoc tool runs.

• Linux and macOS: For example, the followingcommand generates the documentation for the packagecom.mypackage and saves the results in the/user/doc/ directory:

  javadoc -d /user/doc/ com.mypackage

• Windows: For example, the following commandgenerates the documentation for the packagecom.mypackageand saves the results in the\user\doc\ directory:

  javadoc -d \user\doc\ com.mypackage

-docencodingname

Specifies the encoding of the generated HTML files. The name shouldbe a preferred MIME name as specified in theIANA Registry,Character Sets.

Three options are available for use in ajavadocencoding command. The-encoding option is used for encodingthe files read by thejavadoc tool, while the-docencoding and-charset options are used forencoding the files written by the tool. Of the three available options,at most, only the input and an output encoding option are used in asingle encoding command. If you specify both input and output encodingoptions in a command, they must be the same value. If you specifyneither output option, it defaults to the input encoding.

For example:

javadoc -docencoding "iso-8859-1" mypackage

-docfilessubdirs

Enables deep copying ofdoc-files directories.Subdirectories and all contents are recursively copied to thedestination. For example, the directorydoc-files/example/images and all of its contents arecopied. Use the-excludedocfilessubdiroption to restrict the subdirectories to be copied.

-doctitlehtml-code

Specifies the title to place near the top of the overview summary file.The text specified in thetitle tag is placed as acentered, level-one heading directly beneath the navigation bar. Thetitle tag can contain HTML tags and white space, but whenit does, you must enclose the title in quotation marks. Additionalquotation marks within thetitle tag must be escaped. Forexample,javadoc -doctitle "<b>My Library</b><br>v1.0" com.mypackage.

-excludedocfilessubdirname1,name2...

Excludes any subdirectories with the given names when recursivelycopyingdoc-files subdirectories. See-docfilessubdirs. Forhistorical reasons,: can be used anywhere in the argumentas a separator instead of,.

-footerhtml-code

This option is no longer supported and reports a warning.

-groupnamep1,p2...

Group the specified packages together in the Overview page. Forhistorical reasons,: can be used as a separator anywherein the argument instead of,.

-headerhtml-code

Specifies the header text to be placed at the top of each output file.The header is placed to the right of the navigation bar. Theheader can contain HTML tags and white space, but when itdoes, theheader must be enclosed in quotation marks. Useescape characters for internal quotation marks within a header. Forexample,javadoc -header "<b>My Library</b><br>v1.0" com.mypackage.

-helpfilefilename

Specifies a file containing the text that will be displayed when theHELP link in the navigation bar is clicked. If thisoption is not given, thejavadoc tool creates a defaultpage that will be used.

-html5

This option is a no-op and is just retained for backwards compatibility.

--javafx or-javafx

Enables JavaFX functionality. This option is enabled by default if theJavaFX library classes are detected on the module path.

-keywords

Adds HTML keyword<meta> tags to the generatedfile for each class. These tags can help search engines that look for<meta> tags find the pages. Most search engines thatsearch the entire Internet don't look at<meta> tags,because pages can misuse them. Search engines offered by companies thatconfine their searches to their own website can benefit by looking at<meta> tags. The<meta> tagsinclude the fully qualified name of the class and the unqualified namesof the fields and methods. Constructors aren't included because they areidentical to the class name. For example, the page for the classString includes these keywords:

<meta name="keywords" content="java.lang.String class"><meta name="keywords" content="CASE_INSENSITIVE_ORDER"><meta name="keywords" content="length()"><meta name="keywords" content="isEmpty()">

-linkurl

Creates links to existingjavadoc generateddocumentation of externally referenced classes. Theurlargument is the absolute or relative URL of the directory that containsthe externaljavadoc generated documentation. You canspecify multiple-link options in a specifiedjavadoc tool run to link to multiple documents.

Either apackage-list or anelement-listfile must be in thisurl directory (otherwise, use the-linkoffline option).

Note: Thepackage-list andelement-list files are generated by thejavadoc tool when generating the API documentation andshould not be modified by the user.

When you use thejavadoc tool to document packages, ituses thepackage-list file to determine the packagesdeclared in an API. When you generate API documents for modules, thejavadoc tool uses theelement-list file todetermine the modules and packages declared in an API.

Thejavadoc tool reads the names from the appropriatelist file and then links to the packages or modules at that URL.

When thejavadoc tool runs, theurl value iscopied into the<a href> links that are created.Therefore,url must be the URL to the directory and not to afile.

You can use an absolute link forurl to enable yourdocuments to link to a document on any web site, or you can use arelative link to link only to a relative location. If you use a relativelink, then the value you pass in should be the relative path from thedestination directory (specified with the-d option) to thedirectory containing the packages being linked to. When you specify anabsolute link, you usually use an HTTP link. However, if you want tolink to a file system that has no web server, then you can use a filelink. Use a file link only when everyone who wants to access thegenerated documentation shares the same file system. In all cases, andon all operating systems, use a slash as the separator, whether the URLis absolute or relative, andhttps:,http:, orfile: as specified in theRFC 1738: UniformResource Locators (URL).

-link https://<host>/<directory>/<directory>/.../<name>-link http://<host>/<directory>/<directory>/.../<name>-link file://<host>/<directory>/<directory>/.../<name>-link <directory>/<directory>/.../<name>

--link-modularity-mismatch(warn|info)

Specifies whether external documentation with wrong modularity (e.g.non-modular documentation for a modular library, or the reverse case)should be reported as a warning (warn) or just a message(info). The default behavior is to report a warning.

-linkofflineurl1url2

This option is a variation of the-link option. Theyboth create links tojavadoc generated documentation forexternally referenced classes. You can specify multiple-linkoffline options in a specifiedjavadoctool run.

Use the-linkoffline option when:

• Linking to a document on the web that thejavadoctool can't access through a web connection

• Thepackage-list orelement-list fileof the external document either isn't accessible or doesn't exist at theURL location, but does exist at a different location and can bespecified by either thepackage-list orelement-list file (typically local).

Note: Thepackage-list andelement-list files are generated by thejavadoc tool when generating the API documentation andshould not be modified by the user.

Ifurl1 is accessible only on the World Wide Web, then the-linkoffline option removes the constraint that thejavadoc tool must have a web connection to generatedocumentation.

Another use of the-linkoffline option is as awork-around to update documents. After you have run thejavadoc tool on a full set of packages or modules, you canrun thejavadoc tool again on a smaller set of changedpackages or modules, so that the updated files can be inserted back intothe original set.

For example, the-linkoffline option takes twoarguments. The first is for the string to be embedded in the<a href> links, and the second tells thejavadoc tool where to find either thepackage-list orelement-list file.

Theurl1 orurl2 value is the absolute or relativeURL of the directory that contains the externaljavadocgenerated documentation that you want to link to. When relative, thevalue should be the relative path from the destination directory(specified with the-d option) to the root of the packagesbeing linked to. Seeurl in the-link option.

--link-platform-propertiesurl

Specifies a properties file used to configure links to platformdocumentation.

Theurl argument is expected to point to a properties filecontaining one or more entries with the following format, where<version> is the platform version as passed to the--release or--source option and<url> is the base URL of the corresponding platformAPI documentation:

doclet.platform.docs.<version>=<url>

For instance, a properties file containing URLs for releases 15 to 17might contain the following lines:

doclet.platform.docs.15=https://example.com/api/15/doclet.platform.docs.16=https://example.com/api/16/doclet.platform.docs.17=https://example.com/api/17/

If the properties file does not contain an entry for a particularrelease no platform links are generated.

-linksource

Creates an HTML version of each source file (with line numbers) andadds links to them from the standard HTML documentation. Links arecreated for classes, interfaces, constructors, methods, and fields whosedeclarations are in a source file. Otherwise, links aren't created, suchas for default constructors and generated classes.

This option exposes all private implementation details in theincluded source files, including private classes, private fields, andthe bodies of private methods, regardless of the-public,-package,-protected, and-private options. Unless you also use the-private option, not all private classes or interfaces areaccessible through links.

Each link appears on the name of the identifier in its declaration.For example, the link to the source code of theButtonclass would be on the wordButton:

public class Button extends Component implements Accessible

The link to the source code of thegetLabel method intheButton class is on the wordgetLabel:

public String getLabel()

--main-stylesheetfile or-stylesheetfilefile

Specifies the path of an alternate stylesheet file that contains thedefinitions for the CSS styles used in the generated documentation. Thisoption lets you override the default. If you do not specify the option,thejavadoc tool will create and use a default stylesheet.The file name can be any name and isn't restricted tostylesheet.css. The--main-stylesheet optionis the preferred form.

Command-line example:

javadoc --main-stylesheet main_stylesheet.css pkg_foo

-nocomment

Suppresses the entire comment body, including the main description andall tags, and generate only declarations. This option lets you reusesource files that were originally intended for a different purpose sothat you can produce skeleton HTML documentation during the early stagesof a new project.

-nodeprecated

Prevents the generation of any deprecated API in the documentation. Thisdoes what the-nodeprecatedlist option does, and it doesn'tgenerate any deprecated API throughout the rest of the documentation.This is useful when writing code when you don't want to be distracted bythe deprecated code.

-nodeprecatedlist

Prevents the generation of the file that contains the list of deprecatedAPIs (deprecated-list.html) and the link in the navigationbar to that page. Thejavadoc tool continues to generatethe deprecated API throughout the rest of the document. This is usefulwhen your source code contains no deprecated APIs, and you want to makethe navigation bar cleaner.

--no-fonts

Prevents inclusion of font files in the generated documentation. Thiscan be useful if the documentation uses a custom stylesheet which doesnot use the default fonts.

-nohelp

Omits theHELP link in the navigation bar at the top ofeach generated page.

-noindex

Omits the index from the generated documents. The index is produced bydefault.

-nonavbar

Prevents the generation of the navigation bar and header. The-nonavbar option has no effect on the-bottomoption. The-nonavbar option is useful when you areinterested only in the content and have no need for navigation, such aswhen you are converting the files to PostScript or PDF for printingonly.

--no-platform-links

Prevents the generation of links to platform documentation. These linksare generated by default.

-noqualifiername1,name2...

Excludes the list of qualifiers from the output. The package name isremoved from places where class or interface names appear. Forhistorical reasons,: can be used anywhere in the argumentas a separator instead of,.

The following example omits all package qualifiers:-noqualifier all.

The following example omitsjava.lang andjava.io package qualifiers:-noqualifier java.lang:java.io.

The following example omits package qualifiers starting withjava andcom.sun subpackages, but notjavax: -noqualifier java.*:com.sun.*.

Where a package qualifier would appear due to the previous behavior,the name can be suitably shortened. This rule is in effect whether ornot the-noqualifier option is used.

-nosince

Omits from the generated documentation theSince sectionsderived from anysince tags.

-notimestamp

Suppresses the time stamp, which is hidden in an HTML comment in thegenerated HTML near the top of each page. The-notimestampoption is useful when you want to run thejavadoc tool ontwo source bases and compare them, because it prevents time stamps fromcausing a difference (which would otherwise be a difference on everypage). The time stamp includes thejavadoc tool releasenumber.

-notree

Omits the class and interface hierarchy pages from the generateddocuments. These are the pages you reach using theTREElink in the navigation bar. The hierarchy is produced by default.

--override-methods(detail|summary)

Documents overridden methods in the detail or summary sections. Thedefault isdetail.

-overviewfilename

Specifies that thejavadoc tool should retrieve thecontent for the overview documentation from the file specified byfilename and place it on the Overview page(overview-summary.html). If thefilename is arelative path, it is evaluated relative to the current workingdirectory.

The file may be an HTML file, with a filename ending in.html, or a Markdown file, with a filename ending in.md. If the file is an HTML file, the content for theoverview documentation is taken from the<main>element in the file, if one is present, or from the<body> element is there is no<main> element. If the file is a Markdown file, theentire content of the file is used.

The title on the overview page is set by-doctitle.

Note: older versions of thejavadoc toolassumed that any use of this option was for an HTML file, and allowedany extension for thefilename.

-serialwarn

Reports compile-time warnings for missing@serial tags. Bydefault, Javadoc reports no serial warnings. Use this option to displaythe serial warnings, which helps to properly document defaultserializable fields andwriteExternal methods.

--sincerelease(,release)*

Generates documentation for APIs that were added or newly deprecatedin the specifiedreleases.

If the@since tag in thejavadoc comment ofan element in the documented source code matches areleasepassed as the option argument, information about the element and therelease it was added in is included in a "New API" page.

If the "Deprecated API" page is generated and thesinceelement of thejava.lang.Deprecated annotation of adocumented element matches arelease in the option arguments,information about the release the element was deprecated in is added tothe "Deprecated API" page.

Releases are compared using case-sensitive string comparison.

--since-labeltext

Specifies thetext to use in the heading of the "New API" page.This may contain information about the releases covered in the page,e.g. "New API in release 2.0", or "New API since release 1".

--snippet-pathsnippetpathlist

Specifies the search paths for finding files for external snippets. Thesnippetpathlist can contain multiple paths by separating themwith the platform path separator (; on Windows;: on other platforms.) The standard doclet first searchesthesnippet-files subdirectory in the package containingthe snippet, and then searches all the directories in the given list.

-sourcetabtab-length

Specifies the number of spaces each tab uses in the source.

--spec-base-urlurl

Specifies the base URL for relative URLs in@spec tags, tobe used when generating links to any external specifications. It caneither be an absolute URL, or a relative URL, in which case it isevaluated relative to the base directory of the generated output files.The default value is equivalent to{@docRoot}/../specs.

-splitindex

Splits the index file into multiple files, alphabetically, one file perletter, plus a file for any index entries that start withnon-alphabetical symbols.

-tagname:locations:header

Specifies a custom tag with a single argument. For thejavadoc tool to spell-check tag names, it is important toinclude a-tag option for every custom tag that is presentin the source code, disabling (withX) those that aren'tbeing output in the current run. The colon (:) is alwaysthe separator. To include a colon in the tag name, escape it with abackward slash (\). The-tag option outputsthe tag heading,header, in bold, followed on the next line bythe text from its single argument. Similar to any block tag, theargument text can contain inline tags, which are also interpreted. Theoutput is similar to standard one-argument tags, such as the@return and@author tags. Omitting aheader value causes thename to be the heading.locations is a list of characters specifying the kinds ofdeclarations in which the tag may be used. The following characters maybe used, in either uppercase or lowercase:

• A: all declarations
• C: constructors
• F: fields
• M: methods
• O: the overview page and other documentation files indoc-files subdirectories
• P: packages
• S: modules
• T: types (classes and interfaces)
• X: nowhere: the tag is disabled, and will beignored

The order in which tags are given on the command line will be used asthe order in which the tags appear in the generated output. You caninclude standard tags in the order given on the command line by usingthe-tag option with nolocations orheader.

-tagletclass

Specifies the fully qualified name of the taglet used in generatingthe documentation for that tag. Use the fully qualified name for theclass value. This taglet also defines the number of textarguments that the custom tag has. The taglet accepts those arguments,processes them, and generates the output.

Taglets are useful for block or inline tags. They can have any numberof arguments and implement custom behavior, such as making text bold,formatting bullets, writing out the text to a file, or starting otherprocesses. Taglets can only determine where a tag should appear and inwhat form. All other decisions are made by the doclet. A taglet can't dothings such as remove a class name from the list of included classes.However, it can execute side effects, such as printing the tag's text toa file or triggering another process. Use the-tagletpathoption to specify the path to the taglet. The following example insertsthe To Do taglet after Parameters and ahead of Throws in the generatedpages.

-taglet com.sun.tools.doclets.ToDoTaglet-tagletpath /home/taglets-tag return-tag param-tag todo-tag throws-tag see

Alternately, you can use the-taglet option in place ofits-tag option, but that might be difficult to read.

-tagletpathtagletpathlist

Specifies the search paths for finding taglet class files. Thetagletpathlist can contain multiple paths by separating themwith the platform path separator (; on Windows;: on other platforms.) Thejavadoc toolsearches all subdirectories of the specified paths.

-tophtml-code

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

-use

Creates class and package usage pages. Includes one Use page for eachdocumented class and package. The page describes what packages, classes,methods, constructors, and fields use any API of the specified class orpackage. Given class C, things that use class C would include subclassesof C, fields declared as C, methods that return C, and methods andconstructors with parameters of type C. For example, you can look at theUse page for theString type. Because thegetName method in thejava.awt.Font classreturns typeString, thegetName method usesString and so thegetName method appears onthe Use page forString. This documents only uses of theAPI, not the implementation. When a method usesString inits implementation, but doesn't take a string as an argument or return astring, that isn't considered a use ofString. To accessthe generated Use page, go to the class or package and click theUSE link in the navigation bar.

-version

Includes the text of anyversion tags in the generateddocumentation. This text is omitted by default. Note: To find out whatversion of thejavadoc tool you are using, use the--version option (with two hyphens).

-windowtitletitle

Specifies the title to be placed in the HTML<title>tag. The text specified in thetitle tag appears in thewindow title and in any browser bookmarks (favorite places) that someonecreates for this page. This title should not contain any HTML tagsbecause a browser will not interpret them correctly. Use escapecharacters on any internal quotation marks within thetitletag. If the-windowtitle option is omitted, then thejavadoc tool uses the value of the-doctitleoption for the-windowtitle option. For example,javadoc -windowtitle "My Library" com.mypackage.

Extra Options for theStandard Doclet

The following are additional options provided by the standard docletand are subject to change without notice. Additional options are lesscommonly used or are otherwise regarded as advanced.

--datedate-and-time

Specifies the value to be used to timestamp the generated pages, inISO8601 format. The specified value must be within 10 years of thecurrent date and time. It is an error to specify both-notimestamp and--date. Using a specificvalue means the generated documentation can be part of areproducible build. If theoption is not given, the default value is the current date and time. Forexample:

javadoc --date 2022-02-01T17:41:59-08:00 mypackage

--legal-notices(default|none|directory)

Specifies the location from which to copy legal files to the generateddocumentation. If the option is not specified or is used with the valuedefault, the files are copied from the default location. Ifthe argument is used with valuenone, no files are copied.Every other argument is interpreted as directory from which to copy thelegal files.

--no-frames

This option is no longer supported and reports a warning.

-Xdoclint

Enables recommended checks for problems in documentationcomments.

By default, the-Xdoclint option is enabled. Disable itwith the option-Xdoclint:none.

For more details, seeDocLint.

-Xdoclint:flag,flag,...

Enables or disables specific checks for different kinds of issues indocumentation comments.

Eachflag can be one ofall,none,or[-]group wheregroup has one of thefollowing values:accessibility,html,missing,reference,syntax. Formore details on these values, seeDocLintGroups.

When specifying two or more flags, you can either use a single-Xdoclint:... option, listing all the desired flags, or youcan use multiple options giving one or more flag in each option. Forexample, use either of the following commands to check for the HTML,syntax, and accessibility issues in the fileMyFile.java.

javadoc -Xdoclint:html -Xdoclint:syntax -Xdoclint:accessibility MyFile.javajavadoc -Xdoclint:html,syntax,accessibility MyFile.java

The following examples illustrate how to change what DocLintreports:

• -Xdoclint:none --- disables all checks
• -Xdoclint:group --- enablesgroupchecks
• -Xdoclint:all --- enables all groups of checks
• -Xdoclint:all,-group --- enables all checksexceptgroup checks

For more details, seeDocLint.

-Xdoclint/package:[-]packages

Enables or disables checks in specific packages.packages isa comma separated list of package specifiers. A package specifier iseither a qualified name of a package or a package name prefix followedby*, which expands to all subpackages of the givenpackage. Prefix the package specifier with- to disablechecks for the specified packages.

For more details, seeDocLint.

-Xdocrootparenturl

Replaces all@docRoot items followed by/.. indocumentation comments withurl.

DocLint

DocLint provides the ability to check for possible problems indocumentation comments. Problems may be reported as warnings or errors,depending on their severity. For example, a missing comment may be badstyle that deserves a warning, but a link to an unknown Java declarationis more serious and deserves an error. Problems are organized intogroups, and options can be used to enable or disablemessages in one or more groups. Within the source code, messages in oneor more groups can besuppressed byusing@SuppressWarnings annotations.

When invoked fromjavadoc, by default DocLint checks allcomments that are used in the generated documentation. It thus relies onother command-line options to determine which declarations, and whichcorresponding documentation comments will be included.Note:this may mean that even comments on some private members of serializableclasses will also be checked, if the members need to be documented inthe generatedSerialized Forms page.

In contrast, when DocLint is invoked fromjavac, DocLintsolely relies on the various-Xdoclint... options todetermine which documentation comments to check.

DocLint doesn't attempt to fix invalid input, it just reports it.

Note: DocLint doesn't guarantee the completeness of thesechecks. In particular, it isn't a full HTML compliance checker. The goalis to just report common errors in a convenient manner.

Groups

The checks performed by DocLint are organized into groups. Thewarnings and errors in each group can be enabled or disabled withcommand-line options, or suppressed with@SuppressWarningsannotations.

The groups are as follows:

• accessibility --- Checks for issues related toaccessibility.
  For example, noalt attribute specifiedin an<img> element, or no caption or summaryattributes specified in a<table> element.

  Issues are reported as errors if a downstream validation tool mightbe expected to report an error in the files generated byjavadoc.

  For reference, see theWeb ContentAccessibility Guidelines.

• html --- Detects common high-level HTML issues.
  For example, putting block elements inside inline elements, or notclosing elements that require an end tag.

  Issues are reported as errors if a downstream validation tool mightbe expected to report an error in the files generated byjavadoc.

  For reference, see theHTML LivingStandard.

• missing --- Checks for missing documentationcomments or tags.
  For example, a missing comment on a classdeclaration, or a missing@param or@returntag in the comment for a method declaration.

  Issues related to missing items are typically reported as warningsbecause they are unlikely to be reported as errors by downstreamvalidation tools that may be used to check the output generated byjavadoc.

• reference --- Checks for issues relating to thereferences to Java API elements from documentation comment tags.
  Forexample, the reference in@see or{@link ...}cannot be found, or a bad name is given for@param or@throws.

  Issues are typically reported as errors because while the issue maynot cause problems in the generated files, the author has likely made amistake that will lead to incorrect or unexpecteddocumentation.

• syntax --- Checks for low-level syntactic issues indocumentation comments.
  For example, unescaped angle brackets(< and>) and ampersands(&) and invalid documentation comment tags.
  

  Issues are typically reported as errors because the issues may leadto incorrect or unexpected documentation.

Suppressing Messages

DocLint checks for and recognizes two strings that may be present inthe arguments for an@SuppressWarnings annotation.

• doclint
• doclint:LIST

whereLIST is a comma-separated list of one or more ofaccessibility,html,missing,reference,syntax.

The names inLIST are the samegroupnames supported by the command-line-Xdoclint option forjavac andjavadoc. (This is the sameconvention honored by thejavac-Xlint optionand the corresponding names supported by@SuppressWarnings.)

The names inLIST can equivalently be specified in separatearguments of the annotation. For example, the following areequivalent:

• @SuppressWarnings("doclint:accessibility,missing")
• @SuppressWarnings("doclint:accessibility", "doclint:missing")

When DocLint detects an issue in a documentation comment, it checksfor the presence of@SuppressWarnings on the associateddeclaration and on all lexically enclosing declarations. The issue willbe ignored if any such annotation is found containing the simple stringdoclint or the longer formdoclint:LIST whereLIST contains the name of the group for the issue.

Note: as with other uses of@SuppressWarnings,using the annotation on a module or package declaration only affectsthat declaration; it does not affect the contents of the module orpackage in other source files.

All messages related to an issue are suppressed by the presence of anappropriate@SuppressWarnings annotation: this includeserrors as well as warnings.

Note: It is only possible tosuppress messages. Ifan annotation of@SuppressWarnings("doclint") is given on atop-level declaration, all DocLint messages for that declaration and anyenclosed declarations will be suppressed; it is not possible toselectively re-enable messages for issues in enclosed declarations.

Comparison withdownstream validation tools

DocLint is a utility built intojavac andjavadoc that checks the content of documentation comments,as found in source files. In contrast, downstream validation tools canbe used to validate the output generated from those documentationcomments byjavadoc and the standard doclet.

Although there is some overlap in functionality, the two mechanismsare different and each has its own strengths and weaknesses.

• Downstream validation tools can check the end result of anygenerated documentation, as it will be seen by the end user. Thisincludes content from all sources, including documentation comments, thestandard doclet itself, user-provided taglets, and content supplied viacommand-line options. Because such tools are analyzing complete HTMLpages, they can do more complete checks than can DocLint. However, whena problem is found in the generated pages, it can be harder to trackdown exactly where in the build pipeline the problem needs to befixed.

• DocLint checks the content of documentation comments, in sourcefiles. This makes it very easy to identify the exact position of anyissues that may be found. DocLint can also detect some semantic errorsin documentation comments that downstream tools cannot detect, such asmissing comments, using an@return tag in a methodreturningvoid, or an@param tag describing anon-existent parameter. But by its nature, DocLint cannot report onproblems such as missing links, or errors in user-provided customtaglets, or problems in the standard doclet itself. It also cannotreliably detect errors in documentation comments at the boundariesbetween content in a documentation comment and content generated by acustom taglet.