javadoc - The Java API Documentation Generator

Generates HTML pages of API documentation from Java sourcefiles. This document contains Javadoc examples for Solaris.

Reference Guide

ReferenceGuide

SYNOPSIS

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

Arguments can be in any order. Seeprocessing of Source Files fordetails on how the Javadoc tool determines which".java" files to process.

options: Command-line options, as specified in this document. To see atypical use of javadoc options, seeReal-World Example.
packagenames: A series of names of packages, separated by spaces, such asjava.lang java.lang.reflect java.awt. Youmust separately specify each package you want to document.Wildcards are not allowed; use -subpackages for recursion. TheJavadoc tool uses-sourcepath to look for thesepackage names. SeeExample -Documenting One or More Packages
sourcefilenames: A series of source file names, separated by spaces, each ofwhich can begin with a path and contain a wildcard such as asterisk(*). The Javadoc tool will process every file whose name ends with".java", and whose name, when stripped of that suffix, is actuallya legal class name (see the Java Language Specification). Therefore, you can name files with dashes (suchasX-Buffer), or other illegal characters, to preventthem from being documented. This is useful fortest files and template files The path thatprecedes the source file name determines where javadoc will lookfor the file. (The Javadoc tool doesnot use-sourcepath to look for these source file names.)Relative paths are relative to the current directory, so passing inButton.java is identical to./Button.java. A source file name with an absolutepath and a wildcard, for example, is/home/src/java/awt/Graphics*.java. SeeExample - Documenting One or MoreClasses. You can also mix packagenames and sourcefilenames, asinExample - Documenting BothPackages and Classes
-subpackagespkg1:pkg2:...: Generates documentation from source files in the specifiedpackages and recursively in their subpackages. An alternative tosupplying packagenames or sourcefilenames.
@argfiles: One or more files that contain a list of Javadoc options,packagenames and sourcefilenames in any order. Wildcards (*) and-J options are not allowed in these files.

DESCRIPTION

TheJavadoc tool parses the declarations anddocumentation comments in a set of Java source files and produces acorresponding set of HTML pages describing (by default) the publicand protected classes, nested classes (but not anonymous innerclasses), interfaces, constructors, methods, and fields. You canuse it to generate the API (Application Programming Interface)documentation or the implementation documentation for a set ofsource files.

You can run the Javadoc tool onentire packages,individual source files, orboth. When documenting entire packages, youcan either use-subpackagesfor traversing recursively down from a top-level directory, or passin an explicit list of package names. When documenting individualsource files, you pass in a list of source (.java)filenames.Examples are given at the end ofthis document. How Javadoc processes source files is coverednext.

Conformance

The standard doclet does not validate the content of documentation commentsfor conformance nor does it attempt to correct any errors in documentationcomments. Be aware of the problems that may arise when generating non-conformingoutput or output containing executable content, such as JavaScript, when runningthejavadoc command. The standard doclet does provide the-Xdoclint option to help you detect common problems indocumentation comments; however, it is also recommended to check the generatedoutput with any appropriate conformance and checking tools.

For more information about conformance requirements for HTML5 documents, see Conformancerequirements in the HTML5 specification. For more information about security issues related to web pages, seeOpenWeb Application Security Project (OWASP).

Processing of source files

The Javadoc tool processes files that end in".java" plus other files described underSource Files. If you run the Javadoc tool byexplicitly passing in individual source filenames, you candetermine exactly which ".java" files are processed.However, that is not how most developers want to work, as it issimpler to pass in package names. The Javadoc tool can be run threeways without explicitly specifying the source filenames. You can(1) pass in package names, (2) use-subpackages, and (3) use wildcardswith source filenames (*.java). In these cases, theJavadoc tool processes a ".java" file only if itfulfills all of the following requirements:

Its name, after stripping off the ".java" suffix,is actually a legal class name (see the Java Language Specification for legal characters)
Its directory path relative to the root of the source tree isactually a legal package name (after converting its separators todots)
Its package statement contains the legal package name(specified in the previous bullet)

Processing of links -During a run, the Javadoc tool automatically adds cross-referencelinks to package, class and member names that are being documentedas part of that run. Links appear in several places:

Declarations (return types, argument types, field types)
"See Also" sections generated from@see tags
In-line text generated from{@link} tags
Exception names generated from@throws tags
"Specified by" links tomembers in interfaces and "Overrides" links to members inclasses
Summary tables listing packages, classes and members
Package and class inheritance trees
The index

You can add hyperlinks to existing text for classes not includedon the command line (but generated separately) by way of the-link and-linkoffline options.

Otherprocessing details - The Javadoc tool produces one completedocument each time it is run; it cannot do incremental builds --that is, it cannot modify ordirectly incorporate resultsfrom previous runs of the Javadoc tool. However, it can link toresults from other runs, as just mentioned.

As implemented, the Javadoc tool requires and relies on the javacompiler to do its job. The Javadoc tool calls part ofjavac to compile the declarations, ignoring the memberimplementation. It builds a rich internal representation of theclasses, including the class hierarchy, and "use" relationships,then generates the HTML from that. The Javadoc tool also picks upuser-supplied documentation fromdocumentation comments in the sourcecode.

In fact, the Javadoc tool will run on.java sourcefiles that are pure stub files with no method bodies. This meansyou can write documentation comments and run the Javadoc tool inthe earliest stages of design while creating the API, beforewriting the implementation.

Relying on the compiler ensures that the HTML output correspondsexactly with the actual implementation, which may rely on implicit,rather than explicit, source code. For example, the Javadoc tooldocuments default constructors (see Java LanguageSpecification) that are present in the.classfiles but not in the source code.

Inmany cases, the Javadoc tool allows you to generate documentationfor source files whose code is incomplete or erroneous. This is abenefit that enables you to generate documentation before alldebugging and troubleshooting is done. For example, according totheJava Language Specification, a class that contains anabstract method should itself be declared abstract. The Javadoctool does not check for this, and would proceed without a warning,whereas the javac compiler stops on this error. The Javadoc tooldoes do some primitive checking of doc comments. Use theDocCheck doclet to check the doc comments morethoroughly.

When the Javadoc tool builds its internal structure for thedocumentation, it loads all referenced classes. Because of this,the Javadoc tool must be able to find all referenced classes,whether bootstrap classes, extensions, or user classes. For moreabout this, seeHow Classes AreFound. Generally speaking, classes you create must either beloaded as an extension or in the Javadoc tool's class path.

Javadoc Doclets

You can customize the content and format of the Javadoc tool'soutput by using doclets. The Javadoc tool has a default "built-in"doclet, called the standard doclet, that generates HTML-formattedAPI documentation. You can modify or subclass the standard doclet,or write your own doclet to generate HTML, XML, MIF, RTF orwhatever output format you'd like. Information about doclets andtheir use is at the following locations:

When a custom doclet is not specified with the-docletcommand line option, the Javadoc tool will use the default standarddoclet. The javadoc tool has several command line options that areavailable regardless of which doclet is being used. The standarddoclet adds a supplementary set of command line options. Both setsof options are described below in theoptions section.

RelatedDocumentation and Doclets

JavadocEnhancements for details about improvements added inJavadoc.
Javadoc FAQfor answers to common questions, information about Javadoc-relatedtools, and workarounds for bugs.
How to Write Doc Comments for Javadoc for more informationabout Sun conventions for writing documentation comments.
Requirementsfor Writing API Specifications - Standard requirements usedwhen writing the Java SE Platform Specification. It can be usefulwhether you are writing API specifications in source filedocumentation comments or in other formats. It covers requirementsfor packages, classes, interfaces, fields and methods to satisfytestable assertions.
Documentation Comment Specification - The originalspecification on documentation comments, Chapter 18, DocumentationComments, in theJava Language Specification, FirstEdition, by James Gosling, Bill Joy, and Guy Steele. (This chapterwas removed from the second edition.)

Terminology

The termsdocumentation comment,doc comment,main description,tag,block tag, andin-line tag are described atDocumentation Comments. These otherterms have specific meanings within the context of the Javadoctool:

generated document: The document generated by the javadoc tool from the doccomments in Java source code. The default generated document is inHTML and is created by the standard doclet.
name: A name of a program element written in the Java Language --that is, the name of a package, class, interface, field,constructor or method. A name can be fully-qualified, such asjava.lang.String.equals(java.lang.Object), orpartially-qualified, such asequals(Object).
documented classes: The classes and interfaces for which detailed documentation isgenerated during a javadoc run. To be documented, the source filesmust be available, their source filenames or package names must bepassed into the javadoc command, and they must not be filtered outby theiraccess modifier (public, protected,package-private or private). We also refer to these as the classesincluded in the javadoc output, or theincluded classes.
included classes: Classes and interfaces whose details are documented during arun of the Javadoc tool. Same asdocumented classes.
excluded classes: Classes and interfaces whose details arenot documentedduring a run of the Javadoc tool.
referenced classes: The classes and interfaces that are explicitly referred to inthe definition (implementation) or doc comments of the documentedclasses and interfaces. Examples of references include return type,parameter type, cast type, extended class, implemented interface,imported classes, classes used in method bodies, @see, {@link},{@linkplain}, and {@inheritDoc} tags. (Notice this definition haschanged since1.3.) When the Javadoc tool is run, it should load into memoryall of the referenced classes in javadoc's bootclasspath andclasspath. (The Javadoc tool prints a "Class not found" warning forreferenced classes not found.) The Javadoc tool can derive enoughinformation from the .class files to determine their existence andthe fully-qualified names of their members.
external referenced classes: The referenced classes whose documentation is not beinggenerated during a javadoc run. In other words, these classes arenot passed into the Javadoc tool on the command line. Links in thegenerated documentation to those classes are said to beexternalreferences orexternal links. For example, if you runthe Javadoc tool on only thejava.awt package, thenany class injava.lang, such asObject,is an external referenced class. External referenced classes can belinked to using the-link and-linkoffline options. An important property of anexternal referenced class is that its source comments are normallynot available to the Javadoc run. In this case, these commentscannot beinherited.

SOURCE FILES

The Javadoc tool will generate output originating from fourdifferent types of "source" files: Java language source files forclasses (.java), package comment files, overviewcomment files, and miscellaneous unprocessed files. This sectionalso covers test files and template files that can also be in thesource tree, but which you want to be sure not to document.

Class SourceCode Files

Each class or interface and its members can have their owndocumentation comments, contained in a.java file. Formore details about these doc comments, seeDocumentation Comments.

PackageComment Files

Each package can have its own documentation comment, containedin its own "source" file, that the Javadoc tool will merge into thepackage summary page that it generates. You typically include inthis comment any documentation that applies to the entirepackage.

To create a package comment file, you have a choice of two filesto place your comments:

package-info.java - Can contain a packagedeclaration, package annotations, package comments and Javadoctags. This file is generally preferred over package.html.
package.html - Can contain only package commentsand Javadoc tags, no package annotations.

A package may have a singlepackage.html file or asinglepackage-info.java file but not both. Placeeither file in the package directory in the source tree along withyour.java files.

package-info.java - This file can contain apackage comment of the following structure -- the comment is placedbefore the package declaration:

File:java/applet/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;

Note that while the comment separators/** and/* must be present, theleading asterisks on the intermediate linescan be omitted.

package.html - This file can contain apackage comment of the following structure -- the comment is placedin the<body> element:

File:java/applet/package.html

<HTML><BODY>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 appletand the applet context. An applet is an embeddablewindow (see the {@link java.awt.Panel} class) with afew extra methods that the applet context can use toinitialize, start, and stop the applet. @since 1.0 @see java.awt</BODY></HTML>

Notice this is just a normal HTML file and does not include apackage declaration. The content of the package comment file iswritten in HTML, like all other comments, with one exception: Thedocumentation comment should not include the comment separators/** and*/ or leading asterisks. Whenwriting the comment, you should make the first sentence a summaryabout the package, and not put a title or any other text between<body> and the first sentence. You can includepackage tags; as with any documentationcomment, all block tags must appear after the main description. Ifyou add a@see tag in a package comment file, it musthave a fully-qualified name. For more details, see theexample ofpackage.html.

Processing of package comment file - When the Javadoctool runs, it will automatically look for the package comment file;if found, the Javadoc tool does the following:

Copies the comment for processing. (Forpackage.html, copies all content between<body> and</body> HTML tags.You can include a<head> section to put a<title>, source file copyright statement, orother information, but none of these will appear in the generateddocumentation.)
Processes anypackage tags that arepresent.
Inserts the processed text at the bottom of the package summarypage it generates, as shown inPackageSummary.
Copies the first sentence of the package comment to the top ofthe package summary page. It also adds the package name and thisfirst sentence to the list of packages on the overview page, asshown inOverviewSummary. The end-of-sentence is determined by the same rulesused for the end of the first sentence of class and member maindescriptions.

OverviewComment File

Each application or set of packages that you are documenting canhave its own overview documentation comment, kept in its own"source" file, that the Javadoc tool will merge into the overviewpage that it generates. You typically include in this comment anydocumentation that applies to the entire application or set ofpackages.

To create an overview comment file, you can name the fileanything you want, typicallyoverview.html andplace it anywhere, typically at the top level of the source tree.For example, if the source files for thejava.appletpackage are contained in/home/user/src/java/appletdirectory, you could create an overview comment file at/home/user/src/overview.html.

Notice you can have multiple overview comment files for the sameset of source files, in case you want to run javadoc multiple timeson different sets of packages. For example, you could run javadoconce with -private for internal documentation and again withoutthat option for public documentation. In this case, you coulddescribe the documentation as public or internal in the firstsentence of each overview comment file.

The content of the overview comment file is one bigdocumentation comment, written in HTML, like the package commentfile described previously. See that description for details. Tore-iterate, when writing the comment, you should make the firstsentence a summary about the application or set of packages, andnot put a title or any other text between<body>and the first sentence. You can includeoverview tags; as with any documentationcomment, all tags except in-line tags, such as{@link}, must appear after the main description. Ifyou add a@see tag, it must have a fully-qualifiedname.

When you run the Javadoc tool, you specify the overview commentfile name with the-overview option. Thefile is then processed similar to that of a package commentfile.

Copies all content between<body> and</body> tags for processing.
Processes anyoverview tags thatare present.
Inserts the processed text at the bottom of the overview pageit generates, as shown inOverview Summary.
Copies the first sentence of the overview comment to the top ofthe overview summary page.

MiscellaneousUnprocessed Files

You can also include in your source any miscellaneous files thatyou want the Javadoc tool to copy to the destination directory.These typically includes graphic files, example Java source (.java)and class (.class) files, and self-standing HTML files whosecontent would overwhelm the documentation comment of a normal Javasource file.

To include unprocessed files, put them in a directory calleddoc-files which can be a subdirectory of anypackage directory that contains source files. You can have one suchsubdirectory for each package. You might include images, examplecode, source files, .class files, applets and HTML files. Forexample, if you want to include the image of a buttonbutton.gif in thejava.awt.Button classdocumentation, you place that file in the/home/user/src/java/awt/doc-files/ directory. Noticethedoc-files directory should not be located at/home/user/src/java/doc-files becausejava is not a package -- that is, it does not directlycontain any source files.

All links to these unprocessed files must be hard-coded, becausethe Javadoc tool does not look at the files -- it simply copies thedirectory and all its contents to the destination. For example, thelink in theButton.java doc comment might looklike:

    /**     * This button looks like this:      * <img src="doc-files/Button.gif">     */

Test Files and TemplateFiles

Some developers have indicated they want to store test files andtemplates files in the source tree near their corresponding sourcefiles. That is, they would like to put them in the same directory,or a subdirectory, of those source files.

If you run the Javadoc tool by explicitly passing in individualsource filenames, you can deliberately omit test and templatesfiles and prevent them from being processed. However, if you arepassing in package names or wildcards, you need to follow certainrules to ensure these test files and templates files are notprocessed.

Test files differ from template files in that the former arelegal, compilable source files, while the latter are not, but mayend with ".java".

Test files - Often developers want to put compilable,runnable test files for a given package in thesamedirectory as the source files for that package. But they want thetest files to belong to a package other than the source filepackage, such as the unnamed package (so the test files have nopackage statement or a different package statement from thesource). In this scenario, when the source is being documented byspecifying its package name specified on the command line, the testfiles will cause warnings or errors. You need to put such testfiles in a subdirectory. For example, if you want to add test filesfor source files incom.package1, put them in asubdirectory that would be an invalid package name (because itcontains a hyphen):

    com/package1/test-files/

The test directory will be skipped by the Javadoc tool with nowarnings.

If your test files contain doc comments, you can set up aseparate run of the Javadoc tool to produce documentation of thetest files by passing in their test source filenames withwildcards, such ascom/package1/test-files/*.java.

Templates for source files - Template files have namesthat often end in ".java" and are not compilable. If you have atemplate for a source file that you want to keep in the sourcedirectory, you can name it with a dash (such asBuffer-Template.java), or any other illegal Javacharacter, to prevent it from being processed. This relies on thefact that the Javadoc tool will only process source files whosename, when stripped of the ".java" suffix, is actually a legalclass name (see information about Identifiers in the Java Language Specification).

GENERATEDFILES

By default, javadoc uses a standard doclet that generatesHTML-formatted documentation. This doclet generates the followingkinds of files (where each HTML "page" corresponds to a separatefile). Note that javadoc generates files with two types of names:those named after classes/interfaces, and those that are not (suchaspackage-summary.html). Files in the latter groupcontain hyphens to prevent filename conflicts with those in theformer group.

Basic Content Pages

Oneclass or interface page(classname.html) for each class or interface itis documenting.
Onepackage page (package-summary.html) foreach package it is documenting. The Javadoc tool will include anyHTML text provided in a file namedpackage.html orpackage-info.java in the package directory of thesource tree.
Oneoverview page (overview-summary.html)for the entire set of packages. This is the front page of thegenerated document. The Javadoc tool will include any HTML textprovided in a file specified with the-overview option. Note that this fileis created only if you pass into javadoc two or more package names.For further explanation, seeHTMLFrames.)

Cross-Reference Pages

Oneclass hierarchy page for the entire set of packages(overview-tree.html). To view this, click on"Overview" in the navigation bar, then click on "Tree".
Oneclass hierarchy page for each package(package-tree.html) To view this, go to a particularpackage, class or interface page; click "Tree" to display thehierarchy for that package.
One"use" page for each package(package-use.html) and a separate one for each classand interface(class-use/classname.html). Thispage describes what packages, classes, methods, constructors andfields use any part of the given class, interface or package. Givena class or interface A, its "use" page includes subclasses of A,fields declared as A, methods that return A, and methods andconstructors with parameters of type A. You can access this page byfirst going to the package, class or interface, then clicking onthe "Use" link in the navigation bar.
Adeprecated API page(deprecated-list.html) listing all deprecated names.(A deprecated name is not recommended for use, generally due toimprovements, and a replacement name is usually given. DeprecatedAPIs may be removed in future implementations.)
Aconstant field values page(constant-values.html) for the values of staticfields.
Aserialized form page(serialized-form.html) for information aboutserializable and externalizable classes. Each such class has adescription of its serialization fields and methods. Thisinformation is of interest to re-implementors, not to developersusing the API. While there is no link in the navigation bar, youcan get to this information by going to any serialized class andclicking "Serialized Form" in the "See also" section of the classcomment. The standard doclet automatically generates aserialized form page: any class (publicor non-public) that implements Serializable is included, along withreadObject andwriteObject methods, thefields that are serialized, and the doc comments from the@serial,@serialField, and@serialData tags. Publicserializable classes can be excluded by marking them (or theirpackage) with@serial exclude, and package-privateserializable classes can be included by marking them (or theirpackage) with@serial include. As of 1.4, you cangenerate the complete serialized form for public and privateclasses by running javadocwithout specifying the-private option.
Anindex (index-*.html) of all class,interface, constructor, field and method names, alphabeticallyarranged. This is internationalized for Unicode and can begenerated as a single file or as a separate file for each startingcharacter (such as A-Z for English).

Support Files

Ahelp page (help-doc.html) that describesthe navigation bar and the above pages. You can provide your owncustom help file to override the default using-helpfile.
Oneindex.html file which creates the HTML frames fordisplay. This is the file you load to display the front page withframes. This file itself contains no text content.
Severalframe files (*-frame.html)containing lists of packages, classes and interfaces, used whenHTML frames are being displayed.
Apackage list file (package-list), used bythe-link and-linkoffline options. Thisis a text file, not HTML, and is not reachable through any links.
Astyle sheet file (stylesheet.css) thatcontrols a limited amount of color, font family, font size, fontstyle and positioning on the generated pages.
Adoc-files directory that holds any image, example,source code or other files that you want copied to the destinationdirectory. These files are not processed by the Javadoc tool in anymanner -- that is, any javadoc tags in them will be ignored. Thisdirectory is not generated unless it exists in the sourcetree.

HTML Frames

The Javadoc tool will generate either two or three HTML frames,as shown in the figure below. It creates the minimum necessarynumber of frames by omitting the list of packages if there is onlyone package (or no packages). That is, when you pass a singlepackage name or source files (*.java) belonging to a single packageas arguments into the javadoc command, it will create only oneframe (C) in the left-hand column -- the list of classes. When youpass into javadoc two or more package names, it creates a thirdframe (P) listing all packages, as well as an overview page(Detail). This overview page has the filenameoverview-summary.html. Thus, this file is created onlyif you pass in two or more package names. You can bypass frames byclicking on the "No Frames" link or entering atoverview-summary.html.

If you are unfamiliar with HTML frames, you should be aware thatframes can havefocus for printing and scrolling. To give aframe focus, click on it. Then on many browsers the arrow keys andpage keys will scroll that frame, and the print menu command willprint it.

Load one of the following two files as the starting pagedepending on whether you want HTML frames or not:

index.html (for frames)
overview-summary.html (for no frames)

GeneratedFile Structure

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

For example, the document generated for the classjava.applet.Applet class would be located atjava/applet/Applet.html. The file structure for thejava.applet package follows, given that the destination directoryis namedapidocs. 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.

NOTE - Directories are shown inbold. The asterisks(*) indicate the files and directories that areomitted when the arguments to javadoc are source filenames(*.java) rather than package names. Also when arguments are sourcefilenames,package-list is created but is empty. Thedoc-files directory will not be created in the destination unlessit exists in the source tree.

apidocs                             Top directoryindex.html                       Initial page that sets up HTML frames *overview-summary.html            Lists all packages with first sentence summariesoverview-tree.html               Lists class hierarchy for all packagesdeprecated-list.html             Lists deprecated API for all packagesconstant-values.html             Lists values of static fields for all packagesserialized-form.html             Lists serialized form for all packages *overview-frame.html              Lists all packages, used in upper-left frameallclasses-frame.html            Lists all classes for all packages, used in lower-left framehelp-doc.html                    Lists user help for how these pages are organizedindex-all.html                   Default index created without -splitindex optionindex-files                      Directory created with -splitindex optionindex-<number>.html          Index files created with -splitindex optionpackage-list                     Lists package names, used only for resolving external refsstylesheet.css                   HTML style sheet for defining fonts, colors and positionsjava                             Package directoryapplet                       Subpackage directory            Applet.html             Page for Applet class            AppletContext.html      Page for AppletContext interface            AppletStub.html         Page for AppletStub interface            AudioClip.html          Page for AudioClip interface          *package-summary.html    Lists classes with first sentence summaries for this package          *package-frame.html      Lists classes in this package, used in lower left-hand frame          *package-tree.html       Lists class hierarchy for this packagepackage-use             Lists where this package is useddoc-files               Directory holding image and example filesclass-use               Directory holding pages API is used                Applet.html         Page for uses of Applet class                AppletContext.html  Page for uses of AppletContext interface                AppletStub.html     Page for uses of AppletStub interface                AudioClip.html      Page for uses of AudioClip interfacesrc-html                         Source code directoryjava                         Package directoryapplet                   Subpackage directory                Applet.html         Page for Applet source code                AppletContext.html  Page for AppletContext source code                AppletStub.html     Page for AppletStub source code                AudioClip.html      Page for AudioClip source code

Generated API Declarations

The Javadoc tool generates a declaration at the start of eachclass, interface, field, constructor, and method description forthat API item. For example, the declaration for theBoolean class is:

public final class Boolean extends Object implements Serializable

and the declaration for theBoolean.valueOfmethodis:

public static Boolean valueOf(String s)

The Javadoc tool can include the modifierspublic,protected,private,abstract,final,static,transient, andvolatile, but notsynchronized ornative. These last twomodifiers are considered implementation detail and not part of theAPI specification.

Rather than relying on the keywordsynchronized,APIs should document their concurrency semantics in the comment'smain description, as in "a singleEnumeration cannotbe used by multiple threads concurrently". The document should notdescribe how to achieve these semantics. As another example, whileHashtable should be thread-safe, there's no reason tospecify that we achieve this by synchronizing all of its exportedmethods. We should reserve the right to synchronize internally atthe bucket level, thus offering higher concurrency.

DOCUMENTATION COMMENTS

The original "Documentation Comment Specification" can be foundunderrelated documentation.

Commenting the SourceCode

You can includedocumentation comments ("doc comments")in the source code, ahead of declarations for any class, interface,method, constructor, or field. You can also create doc comments foreachpackage and another one for theoverview, though their syntax isslightly different. Doc comments are also known informally as"Javadoc comments" (but this term violates its trademark usage). Adoc comment consists of the characters between the characters/** that begin the comment and the characters*/ that end it.Leadingasterisks are allowed on each line and are described furtherbelow. The text in a comment can continue onto multiple lines.

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

To save space you can put a comment on one line:

/** This comment takes up only one line. */

Placement of comments - Documentation comments arerecognized only when placed immediately before class, interface,constructor, method, or field declarations -- see theclass example,methodexample, andfield example.Documentation comments placed in the body of a method are ignored.Only one documentation comment per declaration statement isrecognized by the Javadoc tool.

A common mistake is to put animport statementbetween the class comment and the class declaration. Avoid this, asthe Javadoc tool will ignore the class comment.

   /**    * This is the class comment for the class Whatever.    */    import com.sun;   // MISTAKE - Important not to put import statement here    public class Whatever {    }

A doc comment is composed of amain description followed by atag section -Themain description begins after the starting delimiter/** and continues until the tag section. Thetagsection starts with the first block tag, which is defined bythe first@ character that begins a line (ignoringleading asterisks, white space, and leading separator/**). It is possible to have a comment with only a tagsection and no main description. The main description cannotcontinue after the tag section begins. The argument to a tag canspan multiple lines. There can be any number of tags -- some typesof tags can be repeated while others cannot. For example, this@see starts the tag section:

/** * This sentence would hold the main description for this doc comment. * @see java.lang.Object */

Block tags and in-line tags - Atag is a special keyword withina doc comment that the Javadoc tool can process. There are twokinds of tags:block tags, which appear as@tag (also known as "standalone tags"), andin-line tags, which appear within curly braces,as{@tag}. To be interpreted, a block tag must appearat the beginning of a line, ignoring leading asterisks, whitespace, and separator (/**). This means you can use the@ character elsewhere in the text and it will not beinterpreted as the start of a tag. If you want to start a line withthe@ character and not have it be interpreted, usethe HTML entity@. Each block tag hasassociated text, which includes any text following the tag up to,but not including, either the next tag, or the end of the doccomment. This associated text can span multiple lines. An in-linetag is allowed and interpreted anywhere that text is allowed. Thefollowing example contains the block tag@deprecatedand in-line tag{@link}.

/** * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */

Comments are written in HTML - The text must be writtenin HTML, in that they should use HTML entities and can use HTMLtags. You can use whichever version of HTML your browser supports;we have written the standard doclet to generate HTML 3.2-compliantcode elsewhere (outside of the documentation comments) with theinclusion of cascading style sheets and frames. (We preface eachgenerated file with "HTML 4.0" because of the frame sets.)

For example, entities for the less-than (<) andgreater-than (>) symbols should be written< and>. Likewise, theampersand (&) should be written&. The bold HTML tag<b> isshown in the following example.

Here is a doc comment:

/** * This is a <b>doc</b> comment. * @see java.lang.Object */

Leadingasterisks - When javadoc parses a doc comment, leading asterisk(*) characters on each line are discarded; blanks andtabs preceding the initial asterisk (*) characters arealso discarded. Starting with 1.4, if you omit the leading asteriskon a line, the leading white space is no longer removed. Thisenables you to paste code examples directly into a doc commentinside a<PRE> tag, and its indentation will behonored. Spaces are generally interpreted by browsers moreuniformly than tabs. Indentation is relative to the left margin(rather than the separator/** or<PRE> tag).

First sentence - The first sentence of each doc commentshould be a summary sentence, containing a concise but completedescription of the declared entity. This sentence ends at the firstperiod that is followed by a blank, tab, or line terminator, or atthe firstblock tag. The Javadoc toolcopies this first sentence to the member summary at the top of theHTML page.

Declaration with multiple fields - Java allows declaringmultiple fields in a single statement, but this statement can haveonly one documentation comment, which is copied for all fields.Therefore if you want individual documentation comments for eachfield, you must declare each field in a separate statement. Forexample, the following documentation comment doesn't make sensewritten as a single declaration and would be better handled as twodeclarations:

/**  * The horizontal and vertical distances of point (x,y) */public int x, y;      // Avoid this

The Javadoc tool generates the following documentation from theabove code:

public intx

The horizontal and vertical distances of point (x,y)

public inty

The horizontal and vertical distances of point (x,y)

Use header tags carefully - When writing documentationcomments for members, it's best not to use HTML heading tags suchas <H1> and <H2>, because the Javadoc tool creates anentire structured document and these structural tags mightinterfere with the formatting of the generated document. However,it is fine to use these headings in class and package comments toprovide your own structure.

Automatic Copying of Method Comments

The Javadoc tool has the ability to copy or "inherit" methodcomments in classes and interfaces under the following twocircumstances. Constructors, fields and nested classes do notinherit doc comments.

Automatically inherit comment to fill in missing text -When amain description, or@return,@param or@throws tag is missing from a method comment, the Javadoc tool copies thecorresponding main description or tag comment from the method itoverrides or implements (if any), according to the algorithm below.
More specifically, when a@param tag for aparticular parameter is missing, then the comment for thatparameter is copied from the method further up the inheritancehierarchy. When a@throws tag for a particularexception is missing, the@throws tag is copiedonly if that exception is declared.
This behavior contrasts with version 1.3 and earlier, where thepresence of any main description or tag would prevent all commentsfrom being inherited.
Explicitly inherit comment with {@inheritDoc} tag -Insert the inline tag{@inheritDoc} in a method maindescription or@return,@param or@throws tag comment -- the corresponding inheritedmain description or tag comment is copied into that spot.

The source file for the inherited method need only be on thepath specified by-sourcepath for the doccomment to actually be available to copy. Neither the class nor itspackage needs to be passed in on the command line. This contrastswith 1.3.x and earlier releases, where the class had to be adocumented class

Inherit from classes and interfaces - Inheriting ofcomments occurs in all three possible cases of inheritance fromclasses and interfaces:

When a method in a class overrides a method in asuperclass
When a method in an interface overrides a method in asuperinterface
When a method in a class implements a method in aninterface

In the first two cases, for method overrides, the Javadoc toolgenerates a subheading "Overrides" in the documentation for theoverriding method, with a link to the method it is overriding,whether or not the comment is inherited.

In the third case, when a method in a given class implements amethod in an interface, the Javadoc tool generates a subheading"Specified by" in the documentation for the overriding method, witha link to the method it is implementing. This happens whether ornot the comment is inherited.

Algorithm for Inheriting MethodComments - If a method does not have a doc comment, or has an{@inheritDoc} tag, the Javadoc tool searches for an applicablecomment using the following algorithm, which is designed to findthe most specific applicable doc comment, giving preference tointerfaces over superclasses:

Look in each directly implemented (or extended) interface inthe order they appear following the word implements (or extends) inthe method declaration. Use the first doc comment found for thismethod.
If step 1 failed to find a doc comment, recursively apply thisentire algorithm to each directly implemented (or extended)interface, in the same order they were examined in step 1.
If step 2 failed to find a doc comment and this is a classother than Object (not an interface):
1. If the superclass has a doc comment for this method, useit.
2. If step 3a failed to find a doc comment, recursively apply thisentire algorithm to the superclass.

JAVADOC TAGS

The Javadoc tool parses special tags when they are embeddedwithin a Java doc comment. These doc tags enable you toautogenerate a complete, well-formatted API from your source code.The tags start with an "at" sign (@) and arecase-sensitive -- they must be typed with the uppercase andlowercase letters as shown. A tag must start at the beginning of aline (after any leading spaces and an optional asterisk) or it istreated as normal text. By convention, tags with the same name aregrouped together. For example, put all@see tagstogether.

Tags come in twotypes:

Block tags - Can be placed only in thetag section that follows the main description.Block tags are of the form:@tag.
Inline tags - Can be placed anywhere in themain description or in the comments forblock tags. Inline tags are denoted by curly braces:{@tag}.

The current tags are:

Tag	Introduced in JDK/SDK
`@author`	1.0
`{@code}`	1.5
`{@docRoot}`	1.3
`@deprecated`	1.0
`@exception`	1.0
`{@inheritDoc}`	1.4
`{@link}`	1.2
`{@linkplain}`	1.4
`{@literal}`	1.5
`@param`	1.0
`@return`	1.0
`@see`	1.0
`@serial`	1.2
`@serialData`	1.2
`@serialField`	1.2
`@since`	1.1
`@throws`	1.2
`{@value}`	1.4
`@version`	1.0

For custom tags, see the-tag option.

@author name-text: Adds an "Author" entry with the specifiedname-textto the generated docs when the -author option is used. A doccomment may contain multiple@author tags. You canspecify one name per@author tag or multiple names pertag. In the former case, the Javadoc tool inserts a comma(,) and space between names. In the latter case, theentire text is simply copied to the generated document withoutbeing parsed. Therefore, you can use multiple names per line if youwant a localized name separator other than comma.

For more details, seeWhere Tags Can BeUsed andwriting @author tags.

@deprecated deprecated-text
Note: You can deprecate a program element using the@Deprecatedannotation.

Adds a comment indicating that this API should no longer be used(even though it may continue to work). The Javadoc tool moves thedeprecated-text ahead of themain description, placing it in italics andpreceding it with a bold warning: "Deprecated". This tag is validin all doc comments: overview, package, class, interface,constructor, method and field.

The first sentence ofdeprecated-text should at leasttell the user when the API was deprecated and what to use as areplacement. The Javadoc tool copies just the first sentence to thesummary section and index. Subsequent sentences can also explainwhy it has been deprecated. You should include a{@link} tag (for Javadoc 1.2 or later) that points tothe replacement API:

For more details, seewriting @deprecated tags.

For Javadoc 1.2 and later, use a{@link} tag. Thiscreates the link in-line, where you want it. For example:
```
/** * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */
```
For Javadoc 1.1, the standard format is to create a@see tag (which cannot be in-line) for each@deprecated tag.

For more about deprecation, seeThe @deprecatedtag.

{@code text}

Equivalent to<code>{@literal}</code>.

Displaystext incode font withoutinterpreting the text as HTML markup or nested javadoc tags. Thisenables you to use regular angle brackets (< and>) instead of the HTML entities(< and>) in doc comments,such as in parameter types (<Object>),inequalities (3 < 4), or arrows(<-). For example, the doc comment text:

{@code A<B>C}

displays in the generated HTML page unchanged, as:

A<B>C

The noteworthy point is that the<B> is notinterpreted as bold and is in code font.

If you want the same functionality without the code font, use{@literal}.

{@docRoot}

Represents the relative path to the generated document's(destination) root directory from any generated page. It is usefulwhen you want to include a file, such as a copyright page orcompany logo, that you want to reference from all generated pages.Linking to the copyright page from the bottom of each page iscommon.

This{@docRoot} tag can be used both on the commandline and in a doc comment: This tag is valid in all doc comments:overview, package, class, interface, constructor, method and field,including the text portion of any tag (such as @return, @param and@deprecated).

On the command line, where the header/footer/bottom aredefined:
```
   javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
```
NOTE - When using{@docRoot} this way in a makefile, some makefile programs require special escaping for the brace{} characters. For example, the Inprise MAKE version 5.2 running onWindows requires double braces:{{@docRoot}}. It alsorequires double (rather than single) quotes to enclose arguments tooptions such as-bottom (with the quotes around thehref argument omitted).

In a doc comment:

   /**    * See the <a href="{@docRoot}/copyright.html">Copyright</a>.    */

The reason this tag is needed is because the generated docs arein hierarchical directories, as deep as the number of subpackages.This expression:

  <a href="{@docRoot}/copyright.html">

would resolve to:

  <a href="../../copyright.html">      for java/lang/Object.java

and

  <a href="../../../copyright.html">   for java/lang/ref/Reference.java

@exception class-name description

The@exception tag is a synonym for@throws.

{@inheritDoc}

Inherits (copies) documentation from the "nearest" inheritable class orimplementable interface into the current doc comment at this tag'slocation. This allows you to write more general comments higher upthe inheritance tree, and to write around the copied text.

This tag is valid only in these places in a doc comment:

In themain description block ofa method. In this case, the main description is copied from a classor interface up the hierarchy.
In the text arguments of the @return, @param and @throws tagsof a method. In this case, the tag text is copied from thecorresponding tag up the hierarchy.

SeeAutomatic Copying of MethodComments for a more precise description of how comments arefound in the inheritance hierarchy. Note that if this tag ismissing, the comment is or is not automatically inherited accordingto rules described in that section.

{@link package.class#member label}

Inserts an in-line link with visible textlabel thatpoints to the documentation for the specified package, class ormembername of a referenced class. This tag isvalid in all doc comments: overview, package, class, interface,constructor, method and field, including the text portion of anytag (such as @return, @param and @deprecated).

This tag is very simliar to@see-- both require the same references and accept exactly the samesyntax forpackage.class#memberandlabel. The main difference is that{@link} generates an in-line link rather than placingthe link in the "See Also" section. Also, the{@link}tag begins and ends with curly braces to separate it from the restof the in-line text. If you need to use "}" inside the label, usethe HTML entity notation }

There is no limit to the number of{@link} tagsallowed in a sentence. You can use this tag in themain description part of any documentationcomment or in the text portion of any tag (such as @deprecated,@return or @param).

For example, here is a comment that refers to thegetComponentAt(int, int) method:

Use the {@link #getComponentAt(int, int) getComponentAt} method.

From this, the standard doclet would generate the following HTML(assuming it refers to another class in the same package):

Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.

Which appears on the web page as:

Use the getComponentAt method.

You can extend{@link} to link to classes not beingdocumented by using the-linkoption.

For more details, seewriting {@link} tags.

{@linkplain package.class#member label}

Identical to{@link}, except the link's label isdisplayed in plain text than code font. Useful when the label isplain text. Example:

     Refer to {@linkplain add() the overridden method}.

This would display as:

Refer to the overridden method.

{@literal text}

Displaystext without interpreting the text as HTMLmarkup or nested javadoc tags. This enables you to use regularangle brackets (< and>) instead ofthe HTML entities (< and>)in doc comments, such as in parameter types(<Object>), inequalities (3 <4), or arrows (<-). For example, the doccomment text:

{@literal A<B>C}

displays unchanged in the generated HTML page in your browser,as:

A<B>C

The noteworthy point is that the<B> is notinterpreted as bold (and it is not in code font).

If you want the same functionality but with the text in codefont, use{@code}.

@param parameter-namedescription

Adds a parameter with the specifiedparameter-namefollowed by the specifieddescription to the"Parameters" section. When writing the doc comment, you maycontinue thedescription onto multiple lines. This tagis valid only in a doc comment for a method, constructor or class.

Theparameter-name can be the name of a parameter ina method or constructor, or the name of a type parameter of aclass, method or constructor. Use angle brackets around thisparameter name to specify the use of a type parameter.

Example of a type parameter of a class:

     /**      * @param <E> Type of element stored in a list      */     public interface List<E> extends Collection<E> {     }

Example of a type parameter of a method:

     /**      * @param string  the string to be converted      * @param type    the type to convert the string to      * @param <T>     the type of the element      * @param <V>     the value of the element      */     <T, V extends T> V convert(String string, Class<T> type) {     }

For more details, seewriting @param tags.

@return description

Adds a "Returns" section with thedescription text.This text should describe the return type and permissible range ofvalues. This tag is valid only in a doc comment for a method.

For more details, seewriting @return tags.

@see reference

Adds a "See Also" heading with a link or text entry that pointstoreference. A doc comment may contain any number of@see tags, which are all grouped under the sameheading. The@see tag has three variations; the thirdform below is the most common. This tag is valid in any doccomment: overview, package, class, interface, constructor, methodor field. For inserting an in-line link within a sentence to apackage, class or member, see{@link}.

@see"string"

Adds a text entry forstring. No link is generated.Thestring is a book or other reference to informationnot available by URL. The Javadoc tool distinguishes this from theprevious cases by looking for a double-quote (") asthe first character. For example:

     @see "The Java Programming Language"

This generates text such as:

See Also:: "The Java Programming Language"

@see<ahref="URL#value">label</a>

Adds a link as defined byURL#value. TheURL#value is a relative or absolute URL. TheJavadoc tool distinguishes this from other cases by looking for aless-than symbol (<) as the first character. Forexample:

     @see <a href="spec.html#section">Java Spec</a>

This generates a link such as:

See Also:: Java Spec

@see package.class#member label

Adds a link, with visible textlabel, that points tothe documentation for the specifiedname in theJava Language that isreferenced.Thelabel is optional; if omitted, the name appearsinstead as the visible text, suitably shortened -- seeHow a name is displayed. Use-noqualifier to globally remove the package namefrom this visible text. Use the label when you want the visibletext to be different from the auto-generated visible text.

Only in version 1.2, just the name but not the label wouldautomatically appear in <code> HTML tags, Starting with1.2.2, the <code> is always included around the visible text,whether or not a label is used.

package.class#memberis any valid program elementname that isreferenced -- a package, class,interface, constructor, method or field name -- except that thecharacter ahead of the member name should be a hash character(#). Theclass represents any top-level ornested class or interface. Themember represents anyconstructor, method or field (not a nested class or interface). Ifthis name is in the documented classes, the Javadoc tool willautomatically create a link to it. To create links toexternal referenced classes, usethe-link option. Use either ofthe other two@see forms for referring todocumentation of a name that does not belong to a referenced class.This argument is described at greater length below underSpecifying a Name.
label is optional text that is visible as thelink's label. Thelabel can contain whitespace. Iflabel is omitted, thenpackage.class.member willappear, suitably shortened relative to the current class andpackage -- seeHow a name isdisplayed.
A space is the delimiter betweenpackage.class#member andlabel. A space inside parentheses does not indicate thestart of a label, so spaces may be used between parameters in amethod.

Example - In this example, an@see tag (intheCharacter class) refers to theequalsmethod in theString class. The tag includes botharguments: the name "String#equals(Object)" and thelabel "equals".

 /**  * @see String#equals(Object) equals  */

The standard doclet produces HTML something like this:

<dl><dt><b>See Also:</b><dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals<code></a></dl>

Which looks something like this in a browser, where the label isthe visible link text:

See Also:: equals

Specifying a name - Thispackage.class#member name can beeither fully-qualified, such asjava.lang.String#toUpperCase() or not, such asString#toUpperCase() or#toUpperCase().If less than fully-qualified, the Javadoc tool uses the normal Javacompiler search order to find it, further described below inSearch order for @see. The name cancontain whitespace within parentheses, such as between methodarguments.

Of course the advantage of providing shorter,"partially-qualified" names is that they are shorter to type andthere is less clutter in the source code. The following table showsthe different forms of the name, whereClass can be aclass or interface,Type can be a class, interface,array, or primitive, andmethod can be a method orconstructor.

Typical forms for @see package.class#member

Referencing a member of the current class
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)
@see #constructor(Type, Type,...)
@see #constructor(Type argname, Type argname,...)

Referencing another class in the current or imported packages
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class#constructor(Type, Type,...)
@see Class#constructor(Type argname, Type argname,...)
@see Class.NestedClass
@see Class

Referencing an element in another package (fullyqualified)
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class#constructor(Type, Type,...)
@see package.Class#constructor(Type argname, Type argname,...)
@see package.Class.NestedClass
@see package.Class
@see package

The following notes apply to the above table:

The first set of forms (with no class or package) will causethe Javadoc tool to search only through the current class'shierarchy. It will find a member of the current class or interface,one of its superclasses or superinterfaces, or one of its enclosingclasses or interfaces (search steps1-3). It will not search the rest of the current package orother packages (search steps 4-5).
If any method or constructor is entered as a name with noparentheses, such asgetValue, and if there is nofield with the same name, the Javadoc tool will correctly create alink to it, but will print a warning message reminding you to addthe parentheses and arguments. If this method is overloaded, theJavadoc tool will link to the first method its search encounters,which is unspecified.
Nested classes must be specified asouter.inner, not simplyinner, for all forms.
As stated, the hash character (#), rather than adot (.) separates a member from its class. Thisenables the Javadoc tool to resolve ambiguities, since the dot alsoseparates classes, nested classes, packages, and subpackages.However, the Javadoc tool is generally lenient and will properlyparse a dot if you know there is no ambiguity, though it will printa warning.

Searchorder for @see - the Javadoc tool will process a@see tag that appears in a source file (.java),package file (package.html or package-info.java) or overview file(overview.html). In the latter two files, you must fully-qualifythe name you supply with@see. In a source file, youcan specify a name that is fully-qualified orpartially-qualified.

When the Javadoc tool encounters a@see tag in a.java file that isnot fully qualified, itsearches for the specified name in the same order as the Javacompiler would (except the Javadoc tool will not detect certainnamespace ambiguities, since it assumes the source code is free ofthese errors). This search order is formally defined in theJava Language Specification.The Javadoc tool searches for that name through all related andimported classes and packages. In particular, it searches in thisorder:

the current class or interface
any enclosing classes and interfaces, searching closestfirst
any superclasses and superinterfaces, searching closestfirst
the current package
any imported packages, classes and interfaces, searching in theorder of the import statement

The Javadoc tool continues to search recursively through steps1-3 for each class it encounters until it finds a match. That is,after it searches through the current class and its enclosing classE, it will search through E's superclasses before E's enclosingclasses. In steps 4 and 5, the Javadoc tool does not search classes orinterfaces within a package in any specified order (that orderdepends on the particular compiler). In step 5, the Javadoc toollooks in java.lang, since that is automatically imported by allprograms.

The Javadoc tool does not necessarily look in subclasses, norwill it look in other packages even if their documentation is beinggenerated in the same run. For example, if the@seetag is in thejava.awt.event.KeyEvent class and refersto a name in thejava.awt package, javadoc does notlook in that package unless that class imports it.

How a name isdisplayed - Iflabel is omitted, thenpackage.class.member appears. In general, it is suitablyshortened relative to the current class and package. By"shortened", we mean the Javadoc tool displays only the minimumname necessary. For example, if theString.toUpperCase() method contains references to amember of the same class and to a member of a different class, theclass name is displayed only in the latter case, as shown in thefollowing table.

Use-noqualifier to globally removethe package names.

Type of Reference	Example in`String.toUpperCase()`	Displays As
`@see` tag refers to member of the same class, samepackage	`@see String#toLowerCase()`	`toLowerCase()` (omits the package and classnames)
`@see` tag refers to member of a different class,same package	`@see Character#toLowerCase(char)`	`Character.toLowerCase(char)` (omits the packagename, includes the class name)
`@see` tag refers to member of a different class,different package	`@see java.io.File#exists()`	`java.io.File.exists()` (includes the package andclass names)

Examplesof @see
The comment to the right shows how the name would be displayed ifthe@see tag is in a class in another package, such asjava.applet.Applet.

                                           See also: @see java.lang.String                   //  String                           @see java.lang.String The String class  //  The String class                 @see String                             //  String                           @see String#equals(Object)              //  String.equals(Object)            @see String#equals                      //  String.equals(java.lang.Object)   @see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)      @see Character#MAX_RADIX                //  Character.MAX_RADIX              @see <a href="spec.html">Java Spec</a>  //  Java Spec            @see "The Java Programming Language"    //  "The Java Programming Language"

You can extend@see to link to classes not beingdocumented by using the-linkoption.

For more details, seewriting @see tags.

@serial field-description| include | exclude

Used in the doc comment for a default serializable field.

An optionalfield-description should explain themeaning of the field and list the acceptable values. If needed, thedescription can span multiple lines. The standard doclet adds thisinformation to theserialized formpage.

If a serializable field was added to a class some time after theclass was made serializable, a statement should be added to itsmain description to identify atwhich version it was added.

Theinclude andexclude argumentsidentify whether a class or package should be included or excludedfrom the serialized form page. They work as follows:

A public or protected class that implementsSerializable isincluded unless that class (orits package) is marked@serial exclude.
A private or package-private class that implementsSerializable isexcluded unless that class (orits package) is marked@serial include.

Examples: Thejavax.swing package is marked@serial exclude (inpackage.html orpackage-info.java). The public classjava.security.BasicPermission is marked@serialexclude. The package-private classjava.util.PropertyPermissionCollection is marked@serial include.

The tag @serial at a class level overrides @serial at a packagelevel.

For more information about how to use these tags, along with anexample, see "DocumentingSerializable Fields and Data for a Class," Section 1.6 of theJava Object Serialization Specification. Also see theSerialization FAQ, which covers common questions, such as "Whydo I see javadoc warnings stating that I am missing @serial tagsfor private fields if I am not running javadoc with the -privateswitch?". Also seeOracle's criteria for including classes in the serialized formspecification.

@serialField field-name field-type field-description

Documents anObjectStreamField component of aSerializable class'sserialPersistentFields member. One@serialField tag should be used for eachObjectStreamField component.

@serialData data-description

Thedata-description documents the types and orderof data in the serialized form. Specifically, this data includesthe optional data written by thewriteObject methodand all data (including base classes) written by theExternalizable.writeExternal method.

The@serialData tag can be used in the doc commentfor thewriteObject,readObject,writeExternal,readExternal,writeReplace, andreadResolvemethods.

@since since-text

Adds a "Since" heading with the specifiedsince-textto the generated documentation. The text has no special internalstructure. This tag is valid in any doc comment: overview, package,class, interface, constructor, method or field. This tag means thatthis change or feature has existed since the software releasespecified by thesince-text. For example:

    @since 1.5

For source code in the Java platform, this tag indicates theversion of the Java platform API specification (not necessarilywhen it was added to the reference implementation). Multiple @sincetags are allowed and are treated like multiple@author tags. You could use multiple tags if theprgram element is used by more than one API.

@throws class-name description

The@throws and@exception tags aresynonyms. Adds a "Throws" subheading to the generateddocumentation, with theclass-name anddescription text. Theclass-name is the nameof the exception that may be thrown by the method. This tag isvalid only in the doc comment for a method or constructor. If thisclass is not fully-specified, the Javadoc tool uses thesearch order to look up this class. Multiple@throws tags can be used in a given doc comment forthe same or different exceptions.

To ensure that all checked exceptions are documented, if a@throws tag does not exist for an exception in thethrows clause, the Javadoc tool automatically adds that exceptionto the HTML output (with no description) as if it were documentedwith @throws tag.

The@throws documentation is copied from anoverridden method to a subclass only when the exception isexplicitly declared in the overridden method. The same is true forcopying from an interface method to an implementing method. You canuse{@inheritDoc} to force @throws toinherit documentation.

For more details, seewriting @throws tags.

{@value package.class#field}

When{@value} is used (without any argument) inthe doc comment of a static field, it displays the value of thatconstant:

    /**     * The value of this constant is {@value}.     */    public static final String SCRIPT_START = "<script>"

When used with argumentpackage.class#field in anydoc comment, it displays the value of the specified constant:

    /**     * Evaluates the script starting with {@value #SCRIPT_START}.     */    public String evalScript(String script) {    }

The argumentpackage.class#field takes a formidentical to that of the@seeargument, except that the member must be a static field.

These values of these constants are also displayed on theConstant FieldValues page.

@version version-text

Adds a "Version" subheading with the specifiedversion-text to the generated docs when the -versionoption is used. This tag is intended to hold the current versionnumber of the software that this code is part of (as opposed to@since, which holds the version number wherethis code was introduced). Theversion-text has nospecial internal structure. To see where the version tag can beused, seeWhere Tags Can Be Used.

A doc comment may contain multiple@version tags.If it makes sense, you can specify one version number per@version tag or multiple version numbers per tag. Inthe former case, the Javadoc tool inserts a comma (,)and space between names. In the latter case, the entire text issimply copied to the generated document without being parsed.Therefore, you can use multiple names per line if you want alocalized name separator other than comma.

For more details, seewriting @version tags.

Where Tags Can BeUsed

The following sections describe where the tags can be used. Notethat these tags can be used in all doc comments:@see,@since,@deprecated,{@link},{@linkplain}, and{@docroot}.

OverviewDocumentation Tags

Overview tags are tags that can appear in the documentationcomment for the overview page (which resides in the source filetypically namedoverview.html). Like in any otherdocumentation comments, these tags must appear after themain description.

NOTE - The{@link} tag has a bug in overviewdocuments in version 1.2 -- the text appears properly but has nolink. The{@docRoot} tag does not currently work inoverview documents.

Overview Tags

PackageDocumentation Tags

Package tags are tags that can appear in the documentationcomment for a package (which resides in the source file namedpackage.html orpackage-info.java). The@serial tag can only be used here with theinclude orexclude argument.

Package Tags

Class and InterfaceDocumentation Tags

The following are tags that can appear in the documentationcomment for a class or interface. The@serial tag canonly be used here with theinclude orexclude argument.

Class/Interface Tags

An example of aclass comment:

/** * 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 DocumentationTags

The following are the tags that can appear in

Field Tags

An example of afield comment:

    /**     * The X-coordinate of the component.     *     * @see #getLocation()     */    int x = 1263732;

Constructor and MethodDocumentation Tags

The following are the tags that can appear in the documentationcomment for a constructor or method, except for@return, which cannot appear in a constructor, and{@inheritDoc}, which hascertainrestrictions. The@serialData tag can only be usedin the doc comment forcertain serializationmethods.

Method/Constructor Tags

An example of amethod doc comment:

    /**     * 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 tool usesdoclets todetermine its output. The Javadoc tool uses the default standarddoclet unless a custom doclet is specified with the -doclet option.The Javadoc tool provides a set of command-line options that can beused with any doclet -- these options are described below under thesub-headingJavadoc Options. Thestandard doclet provides an additional set of command-line optionsthat are described below under the sub-headingOptions Provided by the Standard Doclet. All optionnames are case-insensitive, though their arguments can becase-sensitive.

The options are:

-1.1
-author
-bootclasspath
-bottom
-breakiterator
-charset
-classpath
-d
-docencoding
-docfilessubdirs
-doclet
-docletpath
-doctitle
-encoding
-exclude
-excludedocfilessubdir
-extdirs
-footer
-group

-header
-help
-helpfile
-J
-keywords
-link
-linkoffline
-linksource
-locale
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notimestamp
-notree
-overview
-package

-private
-protected
-public
-quiet
-serialwarn
-source
-sourcepath
-sourcetab
-splitindex
-stylesheetfile
-subpackages
-tag
-taglet
-tagletpath
-top
-title
-use
-verbose
-version
-windowtitle

Options shown initalic are the Javadoc core options,which are provided by the front end of the Javadoc tool and areavailable to all doclets. The standard doclet itself provides thenon-italic options.

Javadoc Options

-overview path/filename

Specifies that javadoc should retrieve the text for theoverview documentation from the "source" file specified bypath/filename and place it on the Overview page(overview-summary.html). Thepath/filename isrelative to the current directory.

While you can use any name you want forfilename andplace it anywhere you want forpath, a typical thing to dois to name itoverview.html and place it in the sourcetree at the directory that contains the topmost packagedirectories. In this location, nopath is needed whendocumenting packages, since-sourcepath will point tothis file. For example, if the source tree for thejava.lang package is/src/classes/java/lang/, then you could place theoverview file at/src/classes/overview.html. SeeReal World Example.

For information about the file specified bypath/filename, seeoverviewcomment file.

Note that the overview page is created only if you pass intojavadoc two or more package names. For further explanation, seeHTML Frames.)

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

-public

Shows only public classes and members.

-protected

Shows only protected and public classes and members. This isthe default.

-package

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

-private

Shows all classes and members.

-help

Displays the online help, which lists these javadoc and docletcommand line options.

-doclet class

Specifies the class file that starts the doclet used ingenerating the documentation. Use the fully-qualified name. Thisdoclet defines the content and formats the output. If the-doclet option is not used, javadoc uses thestandard doclet for generating the default HTML format. This classmust contain thestart(Root) method. The path to thisstarting class is defined by the-docletpath option.

SeeDoclet Overview for more information..

-docletpath classpathlist

Specifies the path to the doclet starting class file (specifiedwith the-doclet option) and any jar files it dependson. If the starting class file is in a jar file, then thisspecifies the path to that jar file, as shown in the example below.You can specify an absolute path or a path relative to the currentdirectory. Ifclasspathlist contains multiple paths orjar files, they should be separated with a colon (:) on Solaris anda semi-colon (;) on Windows. This option is not necessary if thedoclet starting class is already in the search path.

SeeDoclet Overview for more information.

-1.1

This feature has been removed from Javadoc 1.4. There is noreplacement for it. This option created documentation with theappearance and functionality of documentation generated by Javadoc1.1 (it never supported nested classes). If you need this option,use Javadoc 1.2 or 1.3 instead.

-sourcerelease

Specifies the version of source code accepted. The followingvalues forrelease are allowed:

1.5 - javadoc accepts code containing generics and otherlanguage features introduced in JDK 1.5. The compiler defaults tothe 1.5 behavior if the-source flag is not used.
1.4 - javadoc accepts code containing assertions, whichwere introduced in JDK 1.4.
1.3 - javadoc doesnot support assertions,generics, or other language features introduced after JDK 1.3.

Use the value ofrelease corresponding to that used whencompiling the code with javac.

-sourcepath sourcepathlist

Specifies the search paths for finding source files(.java) when passing package names or-subpackages into thejavadoc command.Thesourcepathlist can contain multiple paths by separatingthem with a colon (:). The Javadoc tool will search inall subdirectories of the specified paths. Note that this option isnot only used to locate the source files being documented, but alsoto find source files that are not being documented but whosecomments are inherited by the source files being documented.

Note that you can use the-sourcepath option onlywhen passing package names into the javadoc command -- it will notlocate.java files passed into thejavadoc command. (To locate.java files,cd to that directory or include the path ahead of each file, asshown atDocumenting One or MoreClasses.) If-sourcepath is omitted, javadoc usesthe class path to find the source files (see -classpath). Therefore, the default -sourcepath isthe value of class path. If -classpath is omitted and you arepassing package names into javadoc, it looks in the currentdirectory (and subdirectories) for the source files.

Setsourcepathlist to the root directory of thesource tree for the package you are documenting. For example,suppose you want to document a package calledcom.mypackage whose source files are located at:

  /home/user/src/com/mypackage/*.java

In this case you would specify thesourcepath to/home/user/src, the directory that containscom/mypackage, and then supply the package namecom.mypackage:

  %javadoc -sourcepath /home/user/src/ com.mypackage

This is easy to remember by noticing that if you concatenate thevalue of sourcepath and the package name together and change thedot to a slash "/", you end up with the full path to the package:/home/user/src/com/mypackage.

To point to two source paths:

  %javadoc -sourcepath /home/user1/src:/home/user2/src com.mypackage

-classpath classpathlist

Specifies the paths where javadoc will look forreferenced classes (.classfiles) -- these are the documented classes plus any classesreferenced by those classes. Theclasspathlist can containmultiple paths by separating them with a colon (:).The Javadoc tool will search in all subdirectories of the specifiedpaths. Follow the instructions inclass path documentation for specifyingclasspathlist.

If-sourcepath is omitted, the Javadoc tool uses-classpath to find the source files as well as classfiles (for backward compatibility). Therefore, if you want tosearch for source and class files in separate paths, use both-sourcepath and-classpath.

For example, if you want to documentcom.mypackage,whose source files reside in the directory/home/user/src/com/mypackage, and if this packagerelies on a library in/home/user/lib, you wouldspecify:

  %javadoc -classpath /home/user/lib -sourcepath /home/user/src com.mypackage

As with other tools, if you do not specify-classpath,the Javadoc tool uses the CLASSPATH environment variable, if it isset. If both are not set, the Javadoc tool searches for classesfrom the current directory.

For an in-depth description of how the Javadoc tool uses-classpath to find user classes as it relates toextension classes and bootstrap classes, seeHow Classes Are Found.

As a special convenience, a class path element containing abasename of* is considered equivalent to specifying alist of all the files in the directory with the extension.jar or.JAR (a Java program cannot tellthe difference between the two invocations).

For example, if directoryfoo containsa.jar andb.JAR, then the class pathelementfoo/* is expanded to aA.jar:b.JAR, except that the order of jar files isunspecified. All jar files in the specified directory, even hiddenones, are included in the list. A classpath entry consisting simplyof* expands to a list of all the jar files in thecurrent directory. TheCLASSPATH environment variable,where defined, will be similarly expanded. Any classpath wildcardexpansion occurs before the Java virtual machine is started -- noJava program will ever see unexpanded wildcards except by queryingthe environment. For example; by invokingSystem.getenv("CLASSPATH").

-subpackages package1:package2:...

Generates documentation from source files in the specifiedpackages and recursively in their subpackages. This option isuseful when adding new subpackages to the source code, as they areautomatically included. Eachpackage argument is anytop-level subpackage (such asjava) or fully qualifiedpackage (such asjavax.swing) that does not need tocontain source files. Arguments are separated by colons (on alloperating systmes). Wildcards are not needed or allowed. Use-sourcepath to specify whereto find the packages. This option is smart about not processingsource files that are in the source tree but do not belong to thepackages, as described atprocessing of source files.

For example:

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

This command generates documentation for packages named "java" and"javax.swing" and all their subpackages.

You can use-subpackages in conjunction with-exclude to exclude specificpackages.

-exclude packagename1:packagename2:...

Unconditionally excludes the specified packages and theirsubpackages from the list formed by-subpackages. It excludes thosepackages even if they would otherwise be included by some previousor later-subpackages option. For example:

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

would includejava.io,java.util, andjava.math (among others), but would exclude packagesrooted atjava.net andjava.lang. Noticethis excludesjava.lang.ref, a subpackage ofjava.lang).

-bootclasspath classpathlist

Specifies the paths where the boot classes reside. These arenominally the Java platform classes. The bootclasspath is part ofthe search path the Javadoc tool will use to look up source andclass files. SeeHowClasses Are Found. for more details. Separate directories inclasspathlist with colons (:).

-extdirs dirlist

Specifies the directories where extension classes reside. Theseare any classes that use the Java Extension mechanism. The extdirsis part of the search path the Javadoc tool will use to look upsource and class files. See-classpath (above) formore details. Separate directories indirlist withcolons (:).

-verbose

Provides more detailed messages while javadoc is running.Without the verbose option, messages appear for loading the sourcefiles, generating the documentation (one message per source file),and sorting. The verbose option causes the printing of additionalmessages specifying the number of milliseconds to parse each javasource file.

-quiet

Shuts off non-error and non-warning messages, leaving only thewarnings and errors appear, making them easier to view. Alsosuppresses the version string.

-breakiterator

Uses the internationalized sentence boundary ofjava.text.BreakIteratorto determine the end of the first sentence for English (all otherlocales already useBreakIterator), rather than anEnglish language, locale-specific algorithm. Byfirstsentence, we mean the first sentence in the main descriptionof a package, class or member. This sentence is copied to thepackage, class or member summary, and to the alphabetic index.

From JDK 1.2 forward, the BreakIterator class is already used todetermine the end of sentence for all languages but English.Therefore, the-breakiterator option has no effectexcept for English from 1.2 forward. English has its own defaultalgorithm:

English default sentence-break algorithm - Stops at a periodfollowed by a space or a HTML block tag, such as<P>.
Breakiterator sentence-break algorithm - In general, stops at aperiod, question mark or exclamation mark followed by a space ifthe next word starts with a capital letter. This is meant to handlemost abbreviations (such as "The serial no. is valid", but won'thandle "Mr. Smith"). Doesn't stop at HTML tags or sentences thatbegin with numbers or symbols. Stops at the last period in"../filename", even if embedded in an HTML tag.

NOTE: We have removed from 1.5.0 the breakiterator warningmessages that were in 1.4.x and have left the defaultsentence-break algorithm unchanged. That is, the -breakiteratoroption is not the default in 1.5.0, nor do we expect it to becomethe default. This is a reversal from our former intention that thedefault would change in the "next major release" (1.5.0). Thismeans if you have not modified your source code to eliminate thebreakiterator warnings in 1.4.x, then you don't have to doanything, and the warnings go away starting with 1.5.0. The reasonfor this reversal is because any benefit to having breakiteratorbecome the default would be outweighed by the incompatible sourcechange it would require. We regret any extra work and confusionthis has caused.

-locale language_country_variant

Important - The-locale option must beplacedahead (to the left) of anyoptions provided by the standard doclet or anyother doclet. Otherwise, the navigation bars will appear inEnglish. This is the only command-line option that isorder-dependent.

Specifies the locale that javadoc uses when generatingdocumentation. The argument is the name of the locale, as describedin java.util.Locale documentation, such asen_US(English, United States) oren_US_WIN (Windowsvariant).

Specifying a locale causes javadoc to choose the resource filesof that locale for messages (strings in the navigation bar,headings for lists and tables, help file contents, comments instylesheet.css, and so forth). It also specifies the sorting orderfor lists sorted alphabetically, and the sentence separator todetermine the end of the first sentence. It does not determine thelocale of the doc comment text specified in the source files of thedocumented classes.

-encoding name

Specifies the encoding name of the source files, such asEUCJIS/SJIS. If this option is not specified, theplatform default converter is used.

Also see-docencoding and-charset.

-Jflag

Passesflag directly to the runtime systemjava that runs javadoc. Notice there mustbe no space between theJ and theflag. Forexample, if you need to ensure that the system sets aside 32megabytes of memory in which to process the generateddocumentation, then you would call the-Xmx option of java as follows(-Xms is optional, as it only sets the size of initialmemory, which is useful if you know the minimum amount of memoryrequired):

   %javadoc -J-Xmx32m -J-Xms32mcom.mypackage

To tell what version of javadoc you are using, call the"-version" option of java:

   %javadoc -J-version   java version "1.2"   Classic VM (build JDK-1.2-V, green threads, sunwjit)

(The version number of thestandarddoclet appears in its output stream.)

Options Provided by theStandard Doclet

-d directory

Specifies the destination directory where javadoc saves thegenerated HTML files. (The "d" means "destination.") Omitting thisoption causes the files to be saved to the current directory. Thevaluedirectory can be absolute, or relative to thecurrent working directory. As of 1.4, the destination directory isautomatically created when javadoc is run.

For example, the following generates the documentation for thepackagecom.mypackage and saves the results in the/home/user/doc/ directory:

  %javadoc -d /home/user/doc com.mypackage

-use

Includes one "Use" page for each documented class and package.The page describes what packages, classes, methods, constructorsand fields use any API of the given class or package. Given classC, things that use class C would include subclasses of C, fieldsdeclared as C, methods that return C, and methods and constructorswith parameters of type C.

For example, let us look at what might appear on the "Use" pagefor String. ThegetName() method in thejava.awt.Font class returns typeString.Therefore,getName() usesString, and youwill find that method on the "Use" page forString.

Note that this documents only uses of the API, not theimplementation. If a method usesString in itsimplementation but does not take a string as an argument or returna string, that is not considered a "use" ofString.

You can access the generated "Use" page by first going to theclass or package, then clicking on the "Use" link in the navigationbar.

-version

Includes the @version text in the generated docs. This text isomitted by default. To tell what version of the Javadoc tool youare using, use the-J-version option.

-author

Includes the @author text in the generated docs.

-splitindex

Splits the index file into multiple files, alphabetically, onefile per letter, plus a file for any index entries that start withnon-alphabetical characters.

-windowtitle title

Specifies the title to be placed in the HTML <title> tag.This appears in the window title and in any browser bookmarks(favorite places) that someone creates for this page. This titleshould not contain any HTML tags, as the browser will not properlyinterpret them. Any internal quotation marks withintitlemay have to be escaped. If -windowtitle is omitted, the Javadoctool uses the value of -doctitle for this option.

  %javadoc -windowtitle "Java SE Platform" com.mypackage

-doctitle title

Specifies the title to be placed near the top of the overviewsummary file. The title will be placed as a centered, level-oneheading directly beneath the upper navigation bar. Thetitlemay contain html tags and white space, though if it does, it mustbe enclosed in quotes. Any internal quotation marks withintitle may have to be escaped.

  %javadoc -doctitle "Java™" com.mypackage

-title title

This option no longer exists. It existed only in Betaversions of Javadoc 1.2. It has been renamed to-doctitle. This option is beingrenamed to make it clear that it defines the document title ratherthan the window title.

-header header

Specifies the header text to be placed at the top of eachoutput file. The header will be placed to the right of the uppernavigation bar.header may contain HTML tags and whitespace, though if it does, it must be enclosed in quotes. Anyinternal quotation marks withinheader may have to beescaped.

  %javadoc -header "<b>Java 2 Platform </b><br>v1.4" com.mypackage

-footer footer

Specifies the footer text to be placed at the bottom of eachoutput file. The footer will be placed to the right of the lowernavigation bar.footer may contain html tags and whitespace, though if it does, it must be enclosed in quotes. Anyinternal quotation marks withinfooter may have to beescaped.

-top

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

-bottom text

Specifies the text to be placed at the bottom of each outputfile. The text will be placed at the bottom of the page, below thelower navigation bar. Thetext may contain HTML tags andwhite space, though if it does, it must be enclosed in quotes. Anyinternal quotation marks withintext may have to beescaped.

-link extdocURL

Creates links to existing javadoc-generated documentation ofexternal referencedclasses. It takes one argument:

extdocURL is the absolute or relative URL of thedirectory containing the external javadoc-generated documentationyou want to link to.Examplesare shown below. Thepackage-listfile must be found in this directory (otherwise, use-linkoffline). The Javadoc toolreads the package names from thepackage-list file andthen links to those packages at that URL. When the Javadoc tool isrun, theextdocURL value is copied literally into the<A HREF> links that are created. Therefore,extdocURL must be the URL to thedirectory, not to afile.

You can use an absolute link forextdocURL to enable yourdocs to link to a document on any website, or can use a relativelink to link only to a relative location. If relative, the valueyou pass in should be the relative path from the destinationdirectory (specified with-d) to the directorycontaining the packages being linked to.

When specifying an absolute link you normally use anhttp: link. However, if you want to link to a filesystem that has no web server, you can use afile:link -- however, do this only if everyone wanting to access thegenerated documentation shares the same file system.

In all cases, and on all operating systems, you should use aforward slash as the separator, whether the URL is absolute orrelative, and "http:" or "file:" based (as specified in theURL Memo).
Absolute http: based link:
-linkhttp://<host>/<directory>/<directory>/.../<name>
Absolute file: based link:
-linkfile://<host>/<directory>/<directory>/.../<name>
Relative link:
-link<directory>/<directory>/.../<name>

You can specifymultiple-link options in a given javadoc run to link tomultiple documents.

Choosing between -linkoffline and -link:

Use-link:

when using a relative path to the external API document,or
when using an absolute URL to the external API document, ifyour shell allows a program to open a connection to that URL forreading.

Use-linkoffline:

when using an absolute URL to the external API document, ifyour shelldoes not allow a program to open a connection tothat URL for reading. This can occur if you are behind a firewalland the document you want to link to is on the other side.

Example using absolute links to the external docs - Let ussay you want to link to thejava.lang,java.io and other Java Platform packages athttp://docs.oracle.com/javase/7/docs/api/.The following command generates documentation for the packagecom.mypackage with links to the Java SE Platformpackages. The generated documentation will contain links to theObject class, for example, in the class trees. (Otheroptions, such as-sourcepath and-d, arenot shown.)

  %javadoc -link http://docs.oracle.com/javase/7/docs/api/ com.mypackage

Example using relative links to the external docs - Let ussay you have two packages whose docs are generated in differentruns of the Javadoc tool, and those docs are separated by arelative path. In this example, the packages arecom.apipackage, an API, andcom.spipackage, an SPI (Service Provide Interface).You want the documentation to reside indocs/api/com/apipackage anddocs/spi/com/spipackage. Assuming the API packagedocumentation is already generated, and thatdocs isthe current directory, you would document the SPI package withlinks to the API documentation by running:

  %javadoc -d ./spi -link ../api com.spipackage

Notice the-link argument is relative to thedestination directory (docs/spi).

Details - The-link option enables you tolink to classes referenced to by your code butnotdocumented in the current javadoc run. For these links to go tovalid pages, you must know where those HTML pages are located, andspecify that location withextdocURL. This allows, forinstance, third party documentation to link tojava.*documentation onhttp://docs.oracle.com.

Omit the-link option for javadoc to create linksonly to API within the documentation it is generating in thecurrent run. (Without the-link option, the Javadoctool does not create links to documentation for externalreferences, because it does not know if or where that documentationexists.)

This option can create links inseveralplaces in the generated documentation.

Another use is forcross-linksbetween sets of packages: Execute javadoc on one set of packages,then run javadoc again on another set of packages, creating linksboth ways between both sets.

How a Class Must beReferenced - For a link to an external referenced class toactually appear (and not just its text label), the class must bereferenced in the following way. It is not sufficient for it to bereferenced in the body of a method. It must be referenced in eitheranimport statement or in a declaration. Here areexamples of how the classjava.io.File can bereferenced:

In any kind ofimport statement: by wildcardimport, import explicitly by name, or automatically import forjava.lang.*. For example, this would suffice:
import java.io.*;
In 1.3.x and 1.2.x, only an explicit import by name works -- awildcard import statement does not work, nor does the automaticimportjava.lang.*.
In a declaration:
void foo(File f) {}
The reference and be in the return type or parameter type of amethod, constructor, field, class or interface, or in animplements,extends orthrows statement.

An important corollary is that when you use the-link option, there may be many links thatunintentionally do not appear due to this constraint. (The textwould appear without a hypertext link.) You can detect these by thewarnings they emit. The most innocuous way to properly reference aclass and thereby add the link would be to import that class, asshown above.

PackageList - The-link option requires that a file namedpackage-list, which is generated by the Javadoc tool,exist at the URL you specify with-link. Thepackage-list file is a simple text file that lists thenames of packages documented at that location. In the earlierexample, the Javadoc tool looksfor a file namedpackage-list at the given URL, readsin the package names and then links to those packages at thatURL.

For example, the package list for the Java SE 6 API is locatedathttp://docs.oracle.com/javase/7/docs/api/package-list.and starts as follows:

  java.applet    java.awt  java.awt.color  java.awt.datatransfer  java.awt.dnd  java.awt.event  java.awt.font  etc.

When javadoc is run without the-link option, whenit encounters a name that belongs to anexternal referenced class, itprints the name with no link. However, when the-linkoption is used, the Javadoc tool searches thepackage-list file at the specifiedextdocURLlocation for that package name. If it finds the package name, itprefixes the name withextdocURL.

In order for there to be no broken links, all of thedocumentation for the external references must exist at thespecified URLs. The Javadoc tool will not check that these pagesexist -- only that the package-list exists.

MultipleLinks - You can supply multiple-link options tolink to any number of external generated documents. Javadoc1.2 has a known bug which prevents you from supplying more than one-link command. This was fixed in 1.2.2.

Specify a different link option for each external document tolink to:

%javadoc -linkextdocURL1-linkextdocURL2...-linkextdocURLncom.mypackage

whereextdocURL1, extdocURL2, ...extdocURLn point respectively to the roots of externaldocuments, each of which contains a file namedpackage-list.

Cross-links -Note that "bootstrapping" may be required when cross-linking two ormore documents that have not previously been generated. In otherwords, ifpackage-list does not exist for eitherdocument, when you run the Javadoc tool on the first document, thepackage-list will not yet exist for the seconddocument. Therefore, to create the external links, you mustre-generate the first document after generating the seconddocument.

In this case, the purpose of first generating a document is tocreate itspackage-list (or you can create it by handit if you're certain of the package names). Then generate thesecond document with its external links. The Javadoc tool prints awarning if a needed externalpackage-list file doesnot exist.

-linkoffline extdocURL packagelistLoc

This option is a variation of-link; they bothcreate links to javadoc-generated documentation forexternal referenced classes. Usethe-linkoffline option when linking to a document onthe web when the Javadoc tool itself is "offline" -- that is, itcannot access the document through a web connection.

More specifically, use-linkoffline if the externaldocument'spackage-list file is not accessible or doesnot exist at theextdocURL location but does exist at adifferent location, which can be specified bypackageListLoc(typically local). Thus, ifextdocURL is accessible only onthe World Wide Web,-linkoffline removes theconstraint that the Javadoc tool have a web connection whengenerating the documentation.

Another use is as a "hack" toupdate docs:After you have run javadoc on a full set of packages, then you canrun javadoc again on onlya smaller set of changed packages, so thatthe updated files can be inserted back into the original set.Examples are given below.

The-linkoffline option takes two arguments -- thefirst for the string to be embedded in the<ahref> links, the second telling it where to findpackage-list:

extdocURL is the absolute or relative URL of thedirectory containing the external javadoc-generated documentationyou want to link to. If relative, the value should be the relativepath from the destination directory (specified with-d) to the root of the packages being linked to. Formore details, seeextdocURL in the-link option.
packagelistLoc is the path or URL to thedirectory containing thepackage-list file for theexternal documentation. This can be a URL (http: or file:) or filepath, and can be absolute or relative. If relative, make itrelative to thecurrent directory from where javadoc wasrun. Do not include thepackage-list filename.

You can specifymultiple-linkoffline options in a given javadoc run. (Prior to1.2.2, it could be specified only once.)

Example using absolute linksto the external docs - Let us say you want to link to thejava.lang,java.io and other Java SEPlatform packages athttp://docs.oracle.com/javase/7/docs/api/, butyour shell does not have web access. You could open thepackage-list file in a browser athttp://docs.oracle.com/javase/7/docs/api/package-list,save it to a local directory, and point to this local copy with thesecond argument,packagelistLoc. In this example, thepackage list file has been saved to the current directory"." . The following command generates documentationfor the packagecom.mypackage with links to the JavaSE Platform packages. The generated documentation will containlinks to theObject class, for example, in the classtrees. (Other necessary options, such as-sourcepath,are not shown.)

%javadoc -linkoffline http://docs.oracle.com/javase/7/docs/api/ . com.mypackage

Example using relative links to the external docs - It'snot very common to use-linkoffline with relativepaths, for the simple reason that-link usuallysuffices. When using-linkoffline, thepackage-list file is generally local, and when usingrelative links, the file you are linking to is also generallylocal. So it is usually unnecessary to give a different path forthe two arguments to-linkoffline. When the twoarguments are identical, you can use-link. Seethe-link relativeexample.

Manually Creating apackage-list File - If apackage-list file does not yet exist, but you knowwhat package names your document will link to, you can create yourown copy of this file by hand and specify its path withpackagelistLoc. An example would be the previous case wherethe package list forcom.spipackage did not exist whencom.apipackage was first generated. This technique isuseful when you need to generate documentation that links to newexternal documentation whose package names you know, but which isnot yet published. This is also a way of creatingpackage-list files for packages generated with Javadoc1.0 or 1.1, wherepackage-list files were notgenerated. Likewise, two companies can share their unpublishedpackage-list files, enabling them to release theircross-linked documentation simultaneously.

Linking to Multiple Documents - You can include-linkoffline once for each generated document you wantto refer to (each option is shown on a separate line forclarity):

%javadoc -linkofflineextdocURL1packagelistLoc1

\
          -linkoffline

extdocURL2packagelistLoc2

\
          ...

Updating docs - Anotheruse for-linkoffline option is useful if your projecthas dozens or hundreds of packages, if you have already run javadocon the entire tree, and now, in a separate run, you want to quicklymake some small changes and re-run javadoc on just a small portionof the source tree. This is somewhat of a hack in that it worksproperly only if your changes are only to doc comments and not todeclarations. If you were to add, remove or change any declarationsfrom the source code, then broken links could show up in the index,package tree, inherited member lists, use page, and otherplaces.

First, you create a new destination directory (call itupdate) for this new small run. Let us say theoriginal destination directory was namedhtml. In thesimplest example, cd to the parent ofhtml. Set thefirst argument of-linkoffline to the currentdirectory "." and set the second argument to the relative path tohtml, where it can findpackage-list, andpass in only the package names of the packages you want toupdate:

  %javadoc -d update -linkoffline . html com.mypackage

When the Javadoc tool is done, copy these generated class pages inupdate/com/package (not the overview or index), overthe original files inhtml/com/package.

-linksource

Creates an HTML version of each source file (with line numbers)and adds links to them from the standard HTML documentation. Linksare created for classes, interfaces, constructors, methods andfields whose declarations are in a source file. Otherwise, linksare not created, such as for default constructors and generatedclasses.

This option exposesall private implementation detailsin the included source files, including private classes, privatefields, and the bodies of private methods,regardless of the-public,-package,-protected and-private options.Unless you also use the-private option, not all privateclasses or interfaces will necessarily be accessible via links.

Each link appears on the name of the identifier in itsdeclaration. For example, the link to the source code of theButton class would be on the word "Button":

    public class Button    extends Component    implements Accessible

and the link to the source code of thegetLabel()method in the Button class would be on the word "getLabel":

    public String getLabel()

-group groupheading packagepattern:packagepattern:...

Separates packages on the overview page into whatever groupsyou specify, one group per table. You specify each group with adifferent-group option. The groups appear on the pagein the order specified on the command line; packages arealphabetized within a group. For a given-groupoption, the packages matching the list ofpackagepatternexpressions appear in a table with the headinggroupheading.

groupheading can be any text, and can includewhite space. This text is placed in the table heading for thegroup.
packagepattern can be any package name, orcan be the start of any package name followed by an asterisk(*). The asterisk is a wildcard meaning "match anycharacters". This is the only wildcard allowed. Multiple patternscan be included in a group by separating them with colons(:).

NOTE: If using an asterisk in a pattern or pattern list, thepattern list must be inside quotes, such as"java.lang*:java.util"

If you do not supply any-group option, allpackages are placed in one group with the heading "Packages". Ifthe all groups do not include all documented packages, any leftoverpackages appear in a separate group with the heading "OtherPackages".

For example, the following option separates the four documentedpackages into core, extension and other packages. Notice thetrailing "dot" does not appear in "java.lang*" -- including thedot, such as "java.lang.*" would omit 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

This results in the groupings:

Core Packages: java.lang; java.lang.reflect; java.util
Extension Packages: javax.servlet
Other Packages: java.new

-nodeprecated

Prevents the generation of any deprecated API at all in thedocumentation. This does what -nodeprecatedlist does, plus it doesnot generate any deprecated API throughout the rest of thedocumentation. This is useful when writing code and you don't wantto be distracted by the deprecated code.

-nodeprecatedlist

Prevents the generation of the file containing the list ofdeprecated APIs (deprecated-list.html) and the link in thenavigation bar to that page. (However, javadoc continues togenerate the deprecated API throughout the rest of the document.)This is useful if your source code contains no deprecated API, andyou want to make the navigation bar cleaner.

-nosince

Omits from the generated docs the "Since" sections associatedwith the@since tags.

-notree

Omits the class/interface hierarchy pages from the generateddocs. These are the pages you reach using the "Tree" button in thenavigation bar. The hierarchy is produced by default.

-noindex

Omits the index from the generated docs. The index is producedby default.

-nohelp

Omits the HELP link in the navigation bars at the top andbottom of each page of output.

-nonavbar

Prevents the generation of the navigation bar, header andfooter, otherwise found at the top and bottom of the generatedpages. Has no affect on the "bottom" option. The-nonavbar option is useful when you are interestedonly in the content and have no need for navigation, such asconverting the files to PostScript or PDF for print only.

-helpfile path/filename

Specifies the path of an alternate help filepath/filename that the HELP link in the top and bottomnavigation bars link to. Without this option, the Javadoc toolautomatically creates a help filehelp-doc.html thatis hard-coded in the Javadoc tool. This option enables you tooverride this default. Thefilename can be any name and isnot restricted tohelp-doc.html -- the Javadoc toolwill adjust the links in the navigation bar accordingly. Forexample:

  %javadoc -helpfile /home/user/myhelp.html java.awt

-stylesheetfile path/filename

Specifies the path of an alternate HTML stylesheet file.Without this option, the Javadoc tool automatically creates astylesheet filestylesheet.css that is hard-coded inthe Javadoc tool. This option enables you to override this default.Thefilename can be any name and is not restricted tostylesheet.css. For example:

  %javadoc -stylesheetfile /home/user/mystylesheet.css com.mypackage

-serialwarn

Generates compile-time warnings for missing @serial tags. Bydefault, Javadoc 1.2.2 (and later versions) generates no serialwarnings. (This is a reversal from earlier versions.) Use thisoption to display the serial warnings, which helps to properlydocument default serializable fields andwriteExternalmethods.

-charset name

Specifies the HTML character set for this document. The nameshould be a preferred MIME name as given in theIANA Registry.For example:

  %javadoc -charset "iso-8859-1" mypackage

would insert the following line in the head of every generatedpage:

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

This META tag is described in theHTMLstandard. (4197265 and 4137321)

Also see-encoding and-docencoding.

-docencoding name

Specifies the encoding of the generated HTML files. The nameshould be a preferred MIME name as given in theIANA Registry.If you omit this option but use-encoding,then the encoding of the generated HTML files is determined by-encoding. Example:

  %javadoc -docencoding "ISO-8859-1" mypackage

Also see-encoding and-charset.

-keywords

Adds HTML meta keyword tags to the generated file for eachclass. These tags can help the page be found by search engines thatlook for meta tags. (Most search engines that search the entireInternet do not look at meta tags, because pages can misuse them;but search engines offered by companies that confine their searchto their own website can benefit by looking at meta tags.)

The meta tags include the fully qualified name of the class andthe unqualified names of the fields and methods. Constructors arenot included because they are identical to the class name. Forexample, the class String starts with 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="charAt()">

-tag tagname:Xaoptcmf:"taghead"

Enables the Javadoc tool to interpret a simple, one-argumentcustomblock tag@tagname in doc comments. So the Javadoc toolcan "spell-check" tag names,it is important to include a-tag option for everycustom tag that is present in the source code,disabling (withX) thosethat are not being output in the current run.

The colon (:) is always the separator. Touse a colon intagname, seeUse ofColon in Tag Name.

The-tag option outputs the tag's headingtaghead in bold, followed on the next line by the text fromits single argument, as shown in theexample below. Like any block tag, thisargument's text can contain inline tags, which are alsointerpreted. The output is similar to standard one-argument tags,such as@return and@author. Omittingtaghead causestagname to appear as theheading.

Placement of tags - TheXaoptcmf partof the argument determines where in the source code the tag isallowed to be placed, and whether the tag can be disabled (usingX). You can supply eithera, toallow the tag in all places, or any combination of the otherletters:

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

Examples ofsingle tags - An example of a tag option for a tag that can beused anywhere in the source code is:

    -tag todo:a:"To Do:"

If you wanted @todo to be used only with constructors, methods andfields, you would use:

    -tag todo:cmf:"To Do:"

Notice the last colon (:) above is not a parameterseparator, but is part of the heading text (as shown below). Youwould use either tag option for source code that contains the tag@todo, such as:

     @todo The documentation for this method needs work.

Use of Colon in Tag Name- A colon can be used in a tag name if it is escaped with abackslash. For this doc comment:

    /**     * @ejb:bean     */

use this tag option:

    -tag ejb\\:bean:a:"EJB Bean:"

Spell-checking tag names (Disabling tags) - Some developersput custom tags in the source code that they don't always want tooutput. In these cases, it is important to list all tags that arepresent in the source code, enabling the ones you want to outputand disabling the ones you don't want to output. The presence ofX disables the tag, while its absence enables the tag.This gives the Javadoc tool enough information to know if a tag itencounters is unknown, probably the results of a typo or amisspelling. It prints a warning in these cases.

You can addX to the placement values alreadypresent, so that when you want to enable the tag, you can simplydelete theX. For example, if @todo is a tag that youwant to suppress on output, you would use:

    -tag todo:Xcmf:"To Do:"

or, if you'd rather keep it simple:

    -tag todo:X

The syntax-tag todo:X works even if@todo is defined by a taglet.

Order of tags - The order of the-tag (and-taglet) options determine theorder the tags are output. You can mix the custom tags with thestandard tags to intersperse them. The tag options for standardtags are placeholders only for determining the order -- they takeonly the standard tag's name. (Subheadings for standard tags cannotbe altered.) This is illustrated in the following example.

If-tag is missing, then the position of-taglet determines its order. If they are bothpresent, then whichever appears last on the command line determinesits order. (This happens because the tags and taglets are processedin the order that they appear on the command line. For example, if-taglet and-tag both have the name"todo", the one that appears last on the command line willdetermine its order.

Example of a complete set of tags - This example inserts"To Do" after "Parameters" and before "Throws" in the output. Byusing "X", it also specifies that @example is a tag that might beencountered in the source code that should not be output duringthis run. Notice that if you use@argfile, you can put the tags on separatelines in an argument file like this (no line continuationcharacters needed):

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

When javadoc parses the doc comments, any tag encountered thatis neither a standard tag nor passed in with-tag or-taglet is considered unknown, and a warning isthrown.

The standard tags are initially stored internally in a list intheir default order. Whenever-tag options are used,those tags get appended to this list -- standard tags are movedfrom their default position. Therefore, if a-tagoption is omitted for a standard tag, it remains in its defaultposition.

Avoiding Conflicts - If you want to slice out your ownnamespace, you can use a dot-separated naming convention similar tothat used for packages:com.mycompany.todo. Oraclewill continue to create standard tags whose names do not containdots. Any tag you create will override the behavior of a tag by thesame name defined by Oracle. In other words, if you create a tag ortaglet@todo, it will always have the same behavioryou define, even if Oracle later creates a standard tag of the samename.

Annotations vs. Javadoc Tags - In general, if the markupyou want to add is intended to affect or produce documentation, itshould probably be a javadoc tag; otherwise, it should be anannotation. SeeComparing Annotations and Javadoc Tags<

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

-taglet class

Specifies the class file that starts the taglet used ingenerating the documentation for that tag. Use the fully-qualifiedname forclass. This taglet also defines the number of textarguments that the custom tag has. The taglet accepts thosearguments, processes them, and generates the output. For extensivedocumentation with example taglets, see:

TagletOverview

Taglets are useful for block or inline tags. They can have anynumber of arguments and implement custom behavior, such as makingtext bold, formatting bullets, writing out the text to a file, orstarting other processes.

Taglets can only determine where a tag should appear and in whatform. All other decisions are made by the doclet. So a tagletcannot do things such as remove a class name from the list ofincluded classes. However, it can execute side effects, such asprinting the tag's text to a file or triggering anotherprocess.

Use the-tagletpathoption to specify the path to the taglet. Here is an example thatinserts the "To Do" taglet after "Parameters" and ahead of "Throws"in the generated pages:

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

Alternatively, you can use the-taglet option inplace of its-tag option, but that may be harder toread.

-tagletpath tagletpathlist

Specifies the search paths for findingtaglet class files (.class). Thetagletpathlist can contain multiple paths by separating themwith a colon (:). The Javadoc tool will search in allsubdirectories of the specified paths.

-docfilessubdirs

Enables deep copying of "doc-files" directories.In other words, subdirectories and all contents are recursivelycopied to the destination. For example, the directorydoc-files/example/images and all its contents wouldnow be copied. There is also an option toexclude subdirectories.

-excludedocfilessubdir name1:name2...

Excludes any "doc-files" subdirectories with thegiven names. This prevents the copying of SCCS and othersource-code-control subdirectories.

-noqualifier all | packagename1:packagename2:...

Omits qualifying package name from ahead of class names inoutput. The argument to-noqualifier is either"all" (all package qualifiers are omitted) or acolon-separate list of packages, with wildcards, to be removed asqualifiers. The package name is removed from places whereclass or interface names appear.

The following example omits all package qualifiers:

    -noqualifier all

The following example omits "java.lang" and "java.io" packagequalifiers:

    -noqualifier java.lang:java.io

The following example omits package qualifiers starting with"java", and "com.sun" subpackages (but not "javax"):

    -noqualifier java.*:com.sun.*

Where a package qualifier would appear due to the above behavior,the name can be suitably shortened -- seeHowa name is displayed. This rule is in effect whether or not-noqualifier is used.

-notimestamp

Suppresses the timestamp, which is hidden in an HTML comment inthe generated HTML near the top of each page. Useful when you wantto run javadoc on two source bases and diff them, as it preventstimestamps from causing a diff (which would otherwise be a diff onevery page). The timestamp includes the javadoc version number, andcurrently looks like this:

     <!-- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 -->

-nocomment

Suppress the entire comment body, including themain description and all tags, generatingonly declarations. This option enables re-using source filesoriginally intended for a different purpose, to produce skeletonHTML documentation at the early stages of a new project.

-sourcetabtabLength

Specify the number of spaces each tab takes up in thesource.

COMMAND LINEARGUMENT FILES

To shorten or simplify the javadoc command line, you can specifyone or more files that themselves contain arguments to thejavadoc command (except-J options). Thisenables you to create javadoc commands of any length on anyoperating system.

An argument file can include javac options and source filenamesin any combination. The arguments within a file can bespace-separated or newline-separated. If a filename containsembedded spaces, put the whole filename in double quotes.

Filenames within an argument file are relative to the currentdirectory, not the location of the argument file. Wildcards (*) arenot allowed in these lists (such as for specifying*.java). Use of the '@' character torecursively interpret files is not supported. The-Joptions are not supported because they are passed to the launcher,which does not support argument files.

When executing javadoc, pass in the path and name of eachargument file with the '@' leading character. When javadocencounters an argument beginning with the character `@',it expands the contents of that file into the argument list.

Example - Single Arg File

You could use a single argument file named"argfile" to hold all Javadoc arguments:

  %javadoc @argfile

This argument file could contain the contents of both filesshown in the next example.

Example - Two Arg Files

You can create two argument files -- one for the Javadoc optionsand the other for the package names or source filenames: (Noticethe following lists have no line-continuation characters.)

Create a file named "options" containing:

     -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

Create a file named "packages" containing:

     com.mypackage1     com.mypackage2     com.mypackage3

You would then run javadoc with:

  %javadoc @options @packages

Example - Arg Files with Paths

The argument files can have paths, but any filenames inside thefiles are relative to the current working directory (notpath1 orpath2):

  %javadoc @path1/options @path2/packages

Example - Option Arguments

Here's an example of saving just an argument to a javadoc optionin an argument file. We'll use the-bottom option,since it can have a lengthy argument. You could create a file named"bottom" containing its text argument:

<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>

Then run the Javadoc tool with:

  %javadoc -bottom @bottom @packages

Or you could include the-bottom option at thestart of the argument file, and then just run it as:

  %javadoc @bottom @packages

Running

RUNNINGJAVADOC

VersionNumbers - The version number of javadoc can be determined usingjavadoc -J-version. The version number ofthe standard doclet appears in its output stream. It can be turnedoff with-quiet.

Public programmatic interface - To invoke the Javadoctool from within programs written in the Java language. Thisinterface is incom.sun.tools.javadoc.Main (andjavadoc is re-entrant). For more details, seeStandard Doclet.

Running Doclets - The instructions given below are forinvoking the standard HTML doclet. To invoke a custom doclet, usethe-doclet and-docletpath options. SeeDoclet Overview for more information.

SIMPLE EXAMPLES

You can run javadoc on entire packages or individual sourcefiles. Each package name has a corresponding directory name. In thefollowing examples, the source files are located at/home/src/java/awt/*.java. The destination directoryis/home/html.

Documenting One or More Packages

To document a package, the source files (*.java)for that package must be located in a directory having the samename as the package. If a package name is made up of severalidentifiers (separated by dots, such asjava.awt.color), each subsequent identifier mustcorrespond to a deeper subdirectory (such asjava/awt/color). You may split the source files for asingle package among two such directory trees located at differentplaces, as long as-sourcepath points to them both --for examplesrc1/java/awt/color andsrc2/java/awt/color.

You can run javadoc either by changing directories (withcd) or by using-sourcepath option. Theexamples below illustrate both alternatives.

Case 1 - Run recursively starting from one or morepackages - This example uses -sourcepath so javadoc can be runfrom any directory and -subpackages (a new 1.4 option) forrecursion. It traverses the subpackages of thejavadirectory excluding packages rooted atjava.net andjava.lang. Notice this excludesjava.lang.ref, a subpackage ofjava.lang).
```
  %javadoc-d /home/html-sourcepath /home/src-subpackages java-exclude java.net:java.lang
```
To also traverse down other package trees, append their names tothe-subpackages argument, such asjava:javax:org.xml.sax.
Case 2 - Run on explicit packages after changing to the"root" source directory - Change to the parent directory of thefully-qualified package. Then run javadoc, supplying names of oneor more packages you want to document:
```
  %cd /home/src/  %javadoc -d /home/html java.awt java.awt.event
```
Case 3 - Run from any directory on explicit packages in asingle directory tree - In this case, it doesn't matter whatthe current directory is. Run javadoc supplying-sourcepath with the parent directory of the top-levelpackage, and supplying names of one or more packages you want todocument:
```
  %javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
```
Case 4 - Run from any directory on explicit packages inmultiple directory trees - This is the same as case 3, but forpackages in separate directory trees. Run javadoc supplying-sourcepath with the path to each tree's root(colon-separated) and supply names of one or more packages you wantto document. All source files for a given package do not need to belocated under a single root directory -- they just need to be foundsomewhere along the sourcepath.
```
  %javadoc -d /home/html -sourcepath /home/src1:/home/src2 java.awt java.awt.event
```

Result: All cases generate HTML-formatted documentation for thepublic and protected classes and interfaces in packagesjava.awt andjava.awt.event and save theHTML files in the specified destination directory(/home/html). Because two or more packages are beinggenerated, the document has three HTML frames -- for the list ofpackages, the list of classes, and the main class pages.

Documenting One or More Classes

The second way to run the Javadoc tool is by passing in one ormore source files (.java). You can run javadoc eitherof the following two ways -- by changing directories (withcd) or by fully-specifying the path to the.java files. Relative paths are relative to thecurrent directory. The-sourcepath option is ignoredwhen passing in source files. You can use command line wildcards,such as asterisk (*), to specify groups of classes.

Case 1 - Changing to the source directory - Change tothe directory holding the.java files. Then runjavadoc, supplying names of one or more source files you want todocument.
```
  %cd /home/src/java/awt  %javadoc -d /home/html Button.java Canvas.java Graphics*.java
```
This example generates HTML-formatted documentation for the classesButton,Canvas and classes beginning withGraphics. Because source files rather than packagenames were passed in as arguments to javadoc, the document has twoframes -- for the list of classes and the main page.
Case 2 - Changing to the package root directory - Thisis useful for documenting individual source files from differentsubpackages off the same root. Change to the package rootdirectory, and supply the source files with paths from the root.
```
  %cd /home/src/  %javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
```
This example generates HTML-formatted documentation for the classesButton andApplet.
Case 3 - From any directory - In this case, it doesn'tmatter what the current directory is. Run javadoc supplying theabsolute path (or path relative to the current directory) to the.java files you want to document.
```
  %javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
```
This example generates HTML-formatted documentation for the classButton and classes beginning withGraphics.

DocumentingBoth Packages and Classes

You can document entire packages and individual classes at thesame time. Here's an example that mixes two of the previousexamples. You can use-sourcepath for the path to thepackages but not for the path to the individual classes.

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

This example generates HTML-formatted documentation for thepackagejava.awt and classApplet. (TheJavadoc tool determines the package name forAppletfrom the package declaration, if any, in theApplet.java source file.)

REAL WORLDEXAMPLE

The Javadoc tool has many useful options, some of which are morecommonly used than others. Here is effectively the command we useto run the Javadoc tool on the Java platform API. We use 180MB ofmemory to generate the documentation for the 1500 (approx.) publicand protected classes in the Java SE Platform, Standard Edition,v1.2.

The same example is shown twice -- first as executed on thecommand line, then as executed from a makefile. It uses absolutepaths in the option arguments, which enables the samejavadoc command to be run from any directory.

Command Line Example

The following example may be too long for some shells such asDOS. You can use acommand line argumentfile (or write a shell script) to workaround thislimitation.

% 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

wherepackages is the name of a file containing thepackages to process, such asjava.applet java.lang.None of the options should contain any newline characters betweenthe single quotes. (For example, if you copy and paste thisexample, delete the newline characters from the-bottom option.) See the other notes listed below.

MakefileExample

This is an example of a GNU makefile. For an example of a Windowsmakefile, seecreatinga makefile for Windows.

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'

Single quotes are used to surround makefile arguments.

NOTES

If you omit the-windowtitle option, the Javadoctool copies the doc title to the window title. The-windowtitle text is basically the same as the-doctitle but without HTML tags, to prevent those tagsfrom appearing as raw text in the window title.
If you omit the-footer option, as done here, theJavadoc tool copies the header text to the footer.
Other important options you might want to use but not needed inthis example are -classpathand -link.

TROUBLESHOOTING

General Troubleshooting

Javadoc FAQ - Commonly-encountered bugs andtroubleshooting tips can be found on theJavadocFAQ
Bugs and Limitations - You can also see some bugs listedatImportant Bug Fixes andChanges.
Version number - Seeversionnumbers.
Documents only legal classes - When documenting apackage, javadoc only reads files whose names are composed of legalclass names. You can prevent javadoc from parsing a file byincluding, for example, a hyphen "-" in its filename.

Errorsand Warnings

Error and warning messages contain the filename and line numberto the declaration line rather than to the particular line in thedoc comment.

"error: cannot read: Class1.java" the Javadoc toolis trying to load the class Class1.java in the current directory.The class name is shown with its path (absolute or relative), whichin this case is the same as./Class1.java.

ENVIRONMENT

CLASSPATH: Environment variable that provides the path which javadoc usesto find user class files. This environment variable is overriddenby the-classpath option. Separate directories with acolon, for example:; .:/home/classes:/usr/local/java/classes

Movatterモバイル変換