javadoc(1) Basic Tools javadoc(1) NAME javadoc - Generates HTML pages of API documentation from Java source files. SYNOPSIS javadoc {packages|source-files} [options] [@argfiles] packages Names of packages that you want to document, separated by spaces, for example java.lang java.lang.reflect java.awt. If you want to also document the subpackages, use the -subpackages option to specify the packages. By default, javadoc looks for the specified packages in the current directory and subdirectories. Use the -sourcepath option to specify the list of directories where to look for packages. source-files Names of Java source files that you want to document, separated by spaces, for example Class.java Object.java Button.java. By default, javadoc looks for the specified classes in the current directory. However, you can specify the full path to the class file and use wildcard characters, for example /home/src/java/awt/Graphics*.java. You can also specify the path relative to the current directory. options Command-line options, separated by spaces. See Options. @argfiles Names of files that contain a list of javadoc command options, package names and source file names in any order. DESCRIPTION The javadoc command parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages that describe (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields. You can use the javadoc command to generate the API documentation or the implementation documentation for a set of source files. You can run the javadoc command on entire packages, individual source files, or both. When documenting entire packages, you can either use the -subpackages option to recursively traverse a directory and its subdirectories, or to pass in an explicit list of package names. When you document individual source files, pass in a list of Java source file names. See Simple Examples. PROCESS SOURCE FILES The javadoc command processes files that end in source and other files described in Source Files. If you run the javadoc command by passing in individual source file names, then you can determine exactly which source files are processed. However, that is not how most developers want to work, because it is simpler to pass in package names. The javadoc command can be run three ways without explicitly specifying the source file names. You can pass in package names, use the -subpackages option, or use wild cards with source file names. In these cases, the javadoc command processes a source file only when the file fulfills all of the following requirements: o The file name prefix (with .java removed) is a valid class name. o The path name relative to the root of the source tree is a valid package name after the separators are converted to dots. o The package statement contains the valid package name. Processing Links During a run, the javadoc command adds cross-reference links to package, class, and member names that are being documented as part of that run. Links appear in the following places. See Javadoc Tags for a description of the @ tags. o Declarations (return types, argument types, and field types). o See Also sections that are generated from @see tags. o Inline text generated from {@link} tags. o Exception names generated from @throws tags. o Specified by links to interface members and Overrides links to class members. See Method Comment Inheritance. o Summary tables listing packages, classes and members. o Package and class inheritance trees. o The index. You can add links to existing text for classes not included on the command line (but generated separately) by way of the -link and -linkoffline options. Processing Details The javadoc command produces one complete document every time it runs. It does not do incremental builds that modify or directly incorporate the results from earlier runs. However, the javadoc command can link to results from other runs. The javadoc command implementation requires and relies on the Java compiler. The javadoc command calls part of the javac command to compile the declarations and ignore the member implementations. The javadoc command builds a rich internal representation of the classes that includes the class hierarchy and use relationships to generate the HTML. The javadoc command also picks up user-supplied documentation from documentation comments in the source code. See Documentation Comments. The javadoc command runs on source files that are pure stub files with no method bodies. This means you can write documentation comments and run the javadoc command in the early stages of design before API implementation. Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which may rely on implicit, rather than explicit, source code. For example, the javadoc command documents default constructors that are present in the compiled class files but not in the source code. In many cases, the javadoc command lets you generate documentation for source files with incomplete or erroneous code. You can generate documentation before all debugging and troubleshooting is done. The javadoc command does primitive checking of documentation comments. When the javadoc command builds its internal structure for the documentation, it loads all referenced classes. Because of this, the javadoc command must be able to find all referenced classes, whether bootstrap classes, extensions, or user classes. See How Classes Are Found at http://docs.oracle.com/javase/8/docs/technotes/tools/findingclasses.html Typically, classes you create must either be loaded as an extension or in the javadoc command class path. JAVADOC DOCLETS You can customize the content and format of the javadoc command output with doclets. The javadoc command has a default built-in doclet, called the standard doclet, that generates HTML-formatted API documentation. You can modify or make a subclass of the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you want. When a custom doclet is not specified with the -doclet option, the javadoc command uses the default standard doclet. The javadoc command has several options that are available regardless of which doclet is being used. The standard doclet adds a supplementary set of command- line options. See Options. SOURCE FILES The javadoc command generates output that originates from the following types of source files: Java language source files for classes (.java), package comment files, overview comment files, and miscellaneous unprocessed files. This section also describes test files and template files that can also be in the source tree, but that you want to be sure not to document. CLASS SOURCE FILES Each class or interface and its members can have their own documentation comments contained in a source file. See Documentation Comments. PACKAGE COMMENT FILES Each package can have its own documentation comment, contained in its own source file, that the javadoc command merges into the generated package summary page. You typically include in this comment any documentation that applies to the entire package. To create a package comment file, you can place your comments in one of the following files: o The package-info.java file can contain the package declaration, package annotations, package comments, and Javadoc tags. This file is preferred. o The package.html file contains only package comments and Javadoc tags. No package annotations. A package can have a single package.html file or a single package- info.java file, but not both. Place either file in the package directory in the source tree with your source files. The package-info.java File The package-info.java file can contain a package comment of the following structure. The comment is placed before the package declaration. Note: The comment separators /** and */ must be present, but the leading asterisks on the intermediate lines can be left off. /** * Provides the classes necessary to create an * applet and the classes an applet uses * to communicate with its applet context. *
* 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; The package.html File The package.html file can contain a package comment of the following structure. The comment is placed in the
element. File: java/applet/package.html Provides the classes necessary to create an applet and the classes an applet uses to communicate with its applet context.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 The package.html file is a typical HTML file and does not include a package declaration. The content of the package comment file is written in HTML with one exception. The documentation comment should not include the comment separators /** and */ or leading asterisks. When writing the comment, make the first sentence a summary about the package, and do not put a title or any other text between the
tag and the first sentence. You can include package tags. All block tags must appear after the main description. If you add an @see tag in a package comment file, then it must have a fully qualified name. Processing the Comment File When the javadoc command runs, it searches for the package comment file. If the package comment file is found, then the javadoc command does the following: o Copies the comment for processing. For package.html, the javadoc command copies all content between the and HTML tags. You can include a section to put atag with its indentation preserved. Spaces are interpreted by browsers more uniformly than tabs. Indentation is relative to the left margin (rather than the separator /** ortag). First Sentence The first sentence of each documentation comment should be a summary sentence that contains a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first block tag. The javadoc command copies this first sentence to the member summary at the top of the HTML page. Multiple-Field Declarations The Java platform lets you declare multiple fields in a single statement, but this statement can have only one documentation comment that is copied for all fields. If you want individual documentation comments for each field, then declare each field in a separate statement. For example, the following documentation comment does not make sense written as a single declaration and would be better handled as two declarations: /** * The horizontal and vertical distances of point (x,y) */ public int x, y; // Avoid this The javadoc command generates the following documentation from the previous code: public int x The horizontal and vertical distances of point (x, y). public int y The horizontal and vertical distances of point (x, y). Use of Header Tags When writing documentation comments for members, it is best not to use HTML heading tags such asand
, because the javadoc command creates an entire structured document, and these structural tags might interfere with the formatting of the generated document. However, you can use these headings in class and package comments to provide your own structure. METHOD COMMENT INHERITANCE The javadoc command allows method comment inheritance in classes and interfaces to fill in missing text or to explicitly inherit method comments. Constructors, fields, and nested classes do not inherit documentation comments. Note: The source file for an inherited method must be on the path specified by the -sourcepath option for the documentation comment to be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with Release 1.3.n and earlier releases, where the class had to be a documented class. Fill in Missing Text When a main description, or @return, @param, or @throws tag is missing from a method comment, the javadoc command copies the corresponding main description or tag comment from the method it overrides or implements (if any). See Method Comment Inheritance. When an @param tag for a particular parameter is missing, the comment for that parameter is copied from the method further up the inheritance hierarchy. When an @throws tag for a particular exception is missing, the @throws tag is copied only when that exception is declared. This behavior contrasts with Release 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited. See Javadoc Tags and Options. Explicit Inheritance Insert the {@inheritDoc} inline tag in a method main description or @return, @param, or @throws tag comment. The corresponding inherited main description or tag comment is copied into that spot. CLASS AND INTERFACE INHERITANCE Comment inheritance occurs in all possible cases of inheritance from classes and interfaces: o When a method in a class overrides a method in a superclass o When a method in an interface overrides a method in a superinterface o When a method in a class implements a method in an interface In the first two cases, the javadoc command generates the subheading Overrides in the documentation for the overriding method. A link to the method being overridden is included, whether or not the comment is inherited. In the third case, when a method in a specified class implements a method in an interface, the javadoc command generates the subheading Specified by in the documentation for the overriding method. A link to the method being implemented is included, whether or not the comment is inherited. METHOD COMMENTS ALGORITHM If a method does not have a documentation comment, or has an {@inheritDoc} tag, then the javadoc command uses the following algorithm to search for an applicable comment. The algorithm is designed to find the most specific applicable documentation comment, and to give preference to interfaces over superclasses: 1. Look in each directly implemented (or extended) interface in the order they appear following the word implements (or extends) in the method declaration. Use the first documentation comment found for this method. 2. If Step 1 failed to find a documentation comment, then recursively apply this entire algorithm to each directly implemented (or extended) interface in the same order they were examined in Step 1. 3. When Step 2 fails to find a documentation comment and this is a class other than the Object class, but not an interface: 1. If the superclass has a documentation comment for this method, then use it. 2. If Step 3a failed to find a documentation comment, then recursively apply this entire algorithm to the superclass. JAVADOC TAGS The javadoc command parses special tags when they are embedded within a Java documentation comment. The javadoc tags let you autogenerate a complete, well-formatted API from your source code. The tags start with an at sign (@) and are case-sensitive. They must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk), or it is treated as text. By convention, tags with the same name are grouped together. For example, put all @see tags together. For more information, see Where Tags Can Be Used. Tags have the following types: o Bock tags: Place block tags only in the tag section that follows the description. Block tags have the form: @tag. o Inline tags: Place inline tags anywhere in the main description or in the comments for block tags. Inline tags are enclosed within braces: {@tag}. For custom tags, see -tag tagname:Xaoptcmf:"taghead". See also Where Tags Can Be Used. TAG DESCRIPTIONS @author name-text Introduced in JDK 1.0 Adds an Author entry with the specified name text to the generated documents when the -author option is used. A documentation comment can contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, the javadoc command inserts a comma (,) and space between names. In the latter case, the entire text is copied to the generated document without being parsed. Therefore, you can use multiple names per line if you want a localized name separator other than a comma. See @author in How to Write Doc Comments for the Javadoc Tool at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author {@code text} Introduced in JDK 1.5 Equivalent to
{@literal}
. Displays text in code font without interpreting the text as HTML markup or nested Javadoc tags. This enables you to use regular angle brackets (< and >) instead of the HTML entities (< and >) in documentation comments, such as in parameter types (