neulab/tldr huggingface dataset:
Use header tags carefully - When writing documentation comments for members, it's best not to use HTML heading tags such as <H1> and <H2>, because the Javadoc tool creates an entire structured document and these structural tags might interfere with the formatting of the generated document. However, it is fine to use these headings in class and package comments to provide your own structure.
Automatic Copying of Method Comments The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments.
o Automatically inherit comment to fill in missing text - When a main description, or @return, @param or @throws  tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below.
More specifically, when a @param tag for a particular parameter is missing, then the comment for that parameter is copied from the method further up the inheritance hierarchy. When a @throws tag for a particular exception is missing, the @throws tag is copied only if that exception is declared.
This behavior contrasts with version 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited.
o Explicitly inherit comment with {@inheritDoc} tag - Insert the inline tag {@inheritDoc} 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.
The source file for the inherited method need only be on the path specified by -sourcepath for the doc comment to actually be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with 1.3.x and earlier releases, where the class had to be a documented class
Inherit from classes and interfaces - Inheriting of comments occurs in all three 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, for method overrides, the Javadoc tool generates a subheading "Overrides" in the documentation for the overriding 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 a method in an interface, the Javadoc tool generates a subheading "Specified by" in the documentation for the overriding method, with a link to the method it is implementing. This happens whether or not the comment is inherited.
Algorithm for Inheriting Method Comments - If a method does not have a doc comment, or has an {@inheritDoc} tag, the Javadoc tool searches for an applicable comment using the following algorithm, which is designed to find the most specific applicable doc comment, giving 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 doc comment found for this method.
2. If step 1 failed to find a doc comment, recursively apply this entire algorithm to each directly implemented (or extended) interface, in the same order they were examined in step 1.
3. If step 2 failed to find a doc comment and this is a class other than Object (not an interface):
a. If the superclass has a doc comment for this method, use it.
b. If step 3a failed to find a doc comment, recursively apply this entire algorithm to the superclass.
The Javadoc tool parses special tags when they are embedded within a Java doc comment. These doc tags enable you to 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 normal text. By convention, tags with the same name are grouped together. For example, put all @see tags together.
Tags come in two types:
o Block tags - Can be placed only in the tag section that follows the main description. Block tags are of the form: @tag.
o Inline tags - Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: {@tag}.
For information about tags we might introduce in future releases, see Proposed Tags @ http://java.sun.com/j2se/javadoc/proposed-tags.html.
The current tags are:
For custom tags, see the -tag option.
@author  name-text Adds an "Author" entry with the specified name-text to the generated docs when the -author option is used. A doc comment may contain multiple @author tags. You can specify one name per @author tag or multiple names per tag. In the former case, the Javadoc tool inserts a comma (,) and space between names. In the latter case, the entire text is simply 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 comma.
For more details, see Where Tags Can Be Used and writing @author tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@author.
@deprecated  deprecated-text Note: You can deprecate a program element using the @Deprecated annotation.
Adds a comment indicating that this API should no longer be used (even though it may continue to work). The Javadoc tool moves the deprecated-text ahead of the main description, placing it in italics and preceding it with a bold warning: "Deprecated". This tag is valid in all doc comments: overview, package, class, interface, constructor, method and field.
The first sentence of deprecated-text should at least tell the user when the API was deprecated and what to use as a replacement. The Javadoc tool copies just the first sentence to the summary section and index. Subsequent sentences can also explain why it has been deprecated. You should include a {@link} tag (for Javadoc 1.2 or later) that points to the replacement API:
For more details, see writing @deprecated tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@deprecated.
o For Javadoc 1.2 and later, use a {@link} tag. This creates the link in-line, where you want it. For example: /** * @deprecated  As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */
o 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, see The @deprecated tag @ http://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/index.html.
{@code  text} Equivalent to <code>{@literal}</code>.
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 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 not interpreted 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 useful when you want to include a file, such as a copyright page or company logo, that you want to reference from all generated pages. Linking to the copyright page from the bottom of each page is common.
This {@docRoot} tag can be used both on the command line 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).
1. On the command line, where the header/footer/bottom are defined: javadoc -bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
NOTE - When using {@docRoot} this way in a make file, some makefile programs require special escaping for the brace {} characters. For example, the Inprise MAKE version 5.2 running on Windows requires double braces: {{@docRoot}}. It also requires double (rather than single) quotes to enclose arguments to options such as -bottom (with the quotes around the href argument omitted).
2. In a doc comment: /** * See the <a href="{@docRoot}/copyright.html">Copyright</a>. */
The reason this tag is needed is because the generated docs are in 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 or implementable interface into the current doc comment at this tag's location. This allows you to write more general comments higher up the inheritance tree, and to write around the copied text.
This tag is valid only in these places in a doc comment:
o In the main description block of a method. In this case, the main description is copied from a class or interface up the hierarchy.
o In the text arguments of the @return, @param and @throws tags of a method. In this case, the tag text is copied from the corresponding tag up the hierarchy.
See Automatic Copying of Method Comments for a more precise description of how comments are found in the inheritance hierarchy. Note that if this tag is missing, the comment is or is not automatically inherited according to rules described in that section.
{@link  package.class#member  label} Inserts an in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class. 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).
This tag is very simliar to @see -- both require the same references and accept exactly the same syntax for package.class#member and label. The main difference is that {@link} generates an in-line link rather than placing the link in the "See Also" section. Also, the {@link} tag begins and ends with curly braces to separate it from the rest of the in-line text. If you need to use "}" inside the label, use the HTML entity notation &#125;
There is no limit to the number of {@link} tags allowed in a sentence. You can use this tag in the main description part of any documentation comment or in the text portion of any tag (such as @deprecated, @return or @param).
For example, here is a comment that refers to the getComponentAt(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 being documented by using the -link option.
For more details, see writing {@link} tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#{@link}.
{@linkplain  package.class#member  label} Identical to {@link}, except the link's label is displayed in plain text than code font. Useful when the label is plain text. Example: Refer to {@linkplain add() the overridden method}.
This would display as:
Refer to the overridden method.
{@literal  text} Displays text 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 doc comments, such as in parameter types (<Object>), inequalities (3 < 4), or arrows (<-). For example, the doc comment 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 not interpreted as bold (and it is not in code font).
If you want the same functionality but with the text in code font, use {@code}.
@param  parameter-name description Adds a parameter with the specified parameter-name followed by the specified description to the "Parameters" section. When writing the doc comment, you may continue the description onto multiple lines. This tag is valid only in a doc comment for a method, constructor or class.
The parameter-name can be the name of a parameter in a method or constructor, or the name of a type parameter of a class, method or constructor. Use angle brackets around this parameter 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, see writing @param tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@param.
@return  description Adds a "Returns" section with the description text. This text should describe the return type and permissible range of values. This tag is valid only in a doc comment for a method.
For more details, see writing @return tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return.
@see  reference Adds a "See Also" heading with a link or text entry that points to reference. A doc comment may contain any number of @see tags, which are all grouped under the same heading. The @see tag has three variations; the third form below is the most common. This tag is valid in any doc comment: overview, package, class, interface, constructor, method or field. For inserting an in-line link within a sentence to a package, class or member, see {@link}.
@see "string" Adds a text entry for string. No link is generated. The string is a book or other reference to information not available by URL. The Javadoc tool distinguishes this from the previous cases by looking for a double-quote (") as the first character. For example: @see "The Java Programming Language"
This generates text such as:
See Also: "The Java Programming Language"
@see <a href="URL#value">label</a> Adds a link as defined by URL#value. The URL#value is a relative or absolute URL. The Javadoc tool distinguishes this from other cases by looking for a less-than symbol (<) as the first character. For example: @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 text label, that points to the documentation for the specified name in the Java Language that is referenced. The label is optional; if omitted, the name appears instead as the visible text, suitably shortened -- see How a name is displayed. Use -noqualifier to globally remove the package name from this visible text. Use the label when you want the visible text to be different from the auto-generated visible text.
Only in version 1.2, just the name but not the label would automatically appear in <code> HTML tags, Starting with 1.2.2, the <code> is always included around the visible text, whether or not a label is used.
o package.class#member is any valid program element name that is referenced -- a package, class, interface, constructor, method or field name -- except that the character ahead of the member name should be a hash character (#). The class represents any top-level or nested class or interface. The member represents any constructor, method or field (not a nested class or interface). If this name is in the documented classes, the Javadoc tool will automatically create a link to it. To create links to external referenced classes, use the -link option. Use either of the other two @see forms for referring to documentation of a name that does not belong to a referenced class. This argument is described at greater length below under Specifying a Name.
o label is optional text that is visible as the link's label. The label can contain whitespace. If label is omitted, then package.class.member will appear, suitably shortened relative to the current class and package -- see How a name is displayed.
o A space is the delimiter between package.class#member and label. A space inside parentheses does not indicate the start of a label, so spaces may be used between parameters in a method.
Example - In this example, an @see tag (in the Character class) refers to the equals method in the String class. The tag includes both arguments: the name "String#equals(Object)" and the label "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 is the visible link text:
See Also: equals
Specifying a name - This package.class#member name can be either fully-qualified, such as java.lang.String#toUpperCase() or not, such as String#toUpperCase() or #toUpperCase(). If less than fully-qualified, the Javadoc tool uses the normal Java compiler search order to find it, further described below in Search order for @see. The name can contain whitespace within parentheses, such as between method arguments.
Of course the advantage of providing shorter, "partially-qualified" names is that they are shorter to type and there is less clutter in the source code. The following table shows the different forms of the name, where Class can be a class or interface, Type can be a class, interface, array, or primitive, and method can be a method or constructor.
The following notes apply to the above table:
o The first set of forms (with no class or package) will cause the Javadoc tool to search only through the current class's hierarchy. It will find a member of the current class or interface, one of its superclasses or superinterfaces, or one of its enclosing classes or interfaces (search steps 1-3). It will not search the rest of the current package or other packages (search steps 4-5).
o If any method or constructor is entered as a name with no parentheses, such as getValue, and if there is no field with the same name, the Javadoc tool will correctly create a link to it, but will print a warning message reminding you to add the parentheses and arguments. If this method is overloaded, the Javadoc tool will link to the first method its search encounters, which is unspecified.
o Nested classes must be specified as outer.inner, not simply inner, for all forms.
o As stated, the hash character (#), rather than a dot (.) separates a member from its class. This enables the Javadoc tool to resolve ambiguities, since the dot also separates classes, nested classes, packages, and subpackages. However, the Javadoc tool is generally lenient and will properly parse a dot if you know there is no ambiguity, though it will print a warning.
Search order 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-qualify the name you supply with @see. In a source file, you can specify a name that is fully-qualified or partially-qualified.
When the Javadoc tool encounters a @see tag in a .java file that is not fully qualified, it searches for the specified name in the same order as the Java compiler would (except the Javadoc tool will not detect certain namespace ambiguities, since it assumes the source code is free of these errors). This search order is formally defined in the Java Language Specification. The Javadoc tool searches for that name through all related and imported classes and packages. In particular, it searches in this order:
1. the current class or interface
2. any enclosing classes and interfaces, searching closest first
3. any superclasses and superinterfaces, searching closest first
4. the current package
5. any imported packages, classes and interfaces, searching in the order of the import statement
The Javadoc tool continues to search recursively through steps 1-3 for each class it encounters until it finds a match. That is, after it searches through the current class and its enclosing class E, it will search through E's superclasses before E's enclosing classes. In steps 4 and 5, the Javadoc tool does not search classes or interfaces within a package in any specified order (that order depends on the particular compiler). In step 5, the Javadoc tool looks in java.lang, since that is automatically imported by all programs.
The Javadoc tool does not necessarily look in subclasses, nor will it look in other packages even if their documentation is being generated in the same run. For example, if the @see tag is in the java.awt.event.KeyEvent class and refers to a name in the java.awt package, javadoc does not look in that package unless that class imports it.
How a name is displayed - If label is omitted, then package.class.member appears. In general, it is suitably shortened relative to the current class and package. By "shortened", we mean the Javadoc tool displays only the minimum name necessary. For example, if the String.toUpperCase() method contains references to a member of the same class and to a member of a different class, the class name is displayed only in the latter case, as shown in the following table.
Use -noqualifier to globally remove the package names.
Examples of @see The comment to the right shows how the name would be displayed if the @see tag is in a class in another package, such as java.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 being documented by using the -link option.
For more details, see writing @see tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@see.
@serial  field-description | include | exclude Used in the doc comment for a default serializable field.
An optional field-description should explain the meaning of the field and list the acceptable values. If needed, the description can span multiple lines. The standard doclet adds this information to the serialized form page.
If a serializable field was added to a class some time after the class was made serializable, a statement should be added to its main description to identify at which version it was added.
The include and exclude arguments identify whether a class or package should be included or excluded from the serialized form page. They work as follows:
o A public or protected class that implements Serializable is included unless that class (or its package) is marked @serial exclude.
o A private or package-private class that implements Serializable is excluded unless that class (or its package) is marked @serial include.
Examples: The javax.swing package is marked @serial exclude (in package.html or package-info.java). The public class java.security.BasicPermission is marked @serial exclude. The package-private class java.util.PropertyPermissionCollection is marked @serial include.
The tag @serial at a class level overrides @serial at a package level.
For more information about how to use these tags, along with an example, see " Documenting Serializable Fields and Data for a Class @ http://docs.oracle.com/javase/7/docs/platform/serialization/spec/serial-arch.html," Section 1.6 of the Java Object Serialization Specification. Also see the Serialization FAQ @ http://java.sun.com/javase/technologies/core/basic/serializationFAQ.jsp#javadoc_warn_missing, which covers common questions, such as "Why do I see javadoc warnings stating that I am missing @serial tags for private fields if I am not running javadoc with the -private switch?". Also see Sun's criteria @ http://java.sun.com/j2se/javadoc/writingapispecs/serialized-criteria.html for including classes in the serialized form specification.
@serialField  field-name  field-type  field-description Documents an ObjectStreamField component of a Serializable class's serialPersistentFields member. One @serialField tag should be used for each ObjectStreamField component.
@serialData  data-description The data-description documents the types and order of data in the serialized form. Specifically, this data includes the optional data written by the writeObject method and all data (including base classes) written by the Externalizable.writeExternal method.
The @serialData tag can be used in the doc comment for the writeObject, readObject, writeExternal, readExternal, writeReplace, and readResolve methods.
@since  since-text Adds a "Since" heading with the specified since-text to the generated documentation. The text has no special internal structure. This tag is valid in any doc comment: overview, package, class, interface, constructor, method or field. This tag means that this change or feature has existed since the software release specified by the since-text. For example: @since 1.5
For source code in the Java platform, this tag indicates the version of the Java platform API specification (not necessarily when it was added to the reference implementation). Multiple @since tags are allowed and are treated like multiple @author tags. You could use multiple tags if the prgram element is used by more than one API.
@throws  class-name  description The @throws and @exception tags are synonyms. Adds a "Throws" subheading to the generated documentation, with the class-name and description text. The class-name is the name of the exception that may be thrown by the method. This tag is valid only in the doc comment for a method or constructor. If this class is not fully-specified, the Javadoc tool uses the search order to look up this class. Multiple @throws tags can be used in a given doc comment for the same or different exceptions.
To ensure that all checked exceptions are documented, if a @throws tag does not exist for an exception in the throws clause, the Javadoc tool automatically adds that exception to the HTML output (with no description) as if it were documented with @throws tag.
The @throws documentation is copied from an overridden method to a subclass only when the exception is explicitly declared in the overridden method. The same is true for copying from an interface method to an implementing method. You can use {@inheritDoc} to force @throws to inherit documentation.
For more details, see writing @throws tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@exception.
{@value  package.class#field} When {@value} is used (without any argument) in the doc comment of a static field, it displays the value of that constant: /** * The value of this constant is {@value}. */ public static final String SCRIPT_START = "<script>"
When used with argument package.class#field in any doc comment, it displays the value of the specified constant: /** * Evaluates the script starting with {@value #SCRIPT_START}. */ public String evalScript(String script) { }
The argument package.class#field takes a form identical to that of the @see argument, except that the member must be a static field.
These values of these constants are also displayed on the Constant Field Values @ http://docs.oracle.com/javase/7/docs/api/constant-values.html page.
@version  version-text Adds a "Version" subheading with the specified version-text to the generated docs when the -version option is used. This tag is intended to hold the current version number of the software that this code is part of (as opposed to @since, which holds the version number where this code was introduced). The version-text has no special internal structure. To see where the version tag can be used, see Where 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. In the former case, the Javadoc tool inserts a comma (,) and space between names. In the latter case, the entire text is simply 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 comma.
For more details, see writing @version tags @ http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@version.
Where Tags Can Be Used The following sections describe where the tags can be used. Note that these tags can be used in all doc comments: @see, @since, @deprecated, {@link}, {@linkplain}, and {@docroot}.
Overview Documentation Tags Overview tags are tags that can appear in the documentation comment for the overview page (which resides in the source file typically named overview.html). Like in any other documentation comments, these tags must appear after the main description.
NOTE - The {@link} tag has a bug in overview documents in version 1.2 -- the text appears properly but has no link. The {@docRoot} tag does not currently work in overview documents.
Overview Tags
o @see
o @since
o @author
o @version
o {@link}
o {@linkplain}
o {@docRoot}
Package Documentation Tags Package tags are tags that can appear in the documentation comment for a package (which resides in the source file named package.html or package-info.java). The @serial tag can only be used here with the include or exclude argument.
Package Tags
o @serial
Class and Interface Documentation Tags The following are tags that can appear in the documentation comment for a class or interface. The @serial tag can only be used here with the include or exclude argument.
Class/Interface Tags
o @deprecated
o {@docRoot} An example of a class 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 Documentation Tags The following are the tags that can appear in
Field Tags
o @serialField
o {@value} An example of a field comment: /** * The X-coordinate of the component. * * @see #getLocation() */ int x = 1263732;
Constructor and Method Documentation Tags The following are the tags that can appear in the documentation comment for a constructor or method, except for @return, which cannot appear in a constructor, and {@inheritDoc}, which has certain restrictions. The @serialData tag can only be used in the doc comment for certain serialization methods.
Method/Constructor Tags
o @param
o @return
o @throws and @exception
o @serialData
o {@inheritDoc}
o {@docRoot} An example of a method 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) { ... }
The javadoc tool uses doclets to determine its output. The Javadoc tool uses the default standard doclet unless a custom doclet is specified with the -doclet option. The Javadoc tool provides a set of command-line options that can be used with any doclet -- these options are described below under the sub-heading Javadoc Options. The standard doclet provides an additional set of command-line options that are described below under the sub-heading Options Provided by the Standard Doclet. All option names are case-insensitive, though their arguments can be case-sensitive.
Options shown in italic are the Javadoc core options, which are provided by the front end of the Javadoc tool and are available to all doclets. The standard doclet itself provides the non-italic options.
Javadoc Options -overview  path/filename Specifies that javadoc should retrieve the text for the overview documentation from the "source" file specified by path/filename and place it on the Overview page (overview-summary.html). The path/filename is relative to the current directory. While you can use any name you want for filename and place it anywhere you want for path, a typical thing to do is to name it overview.html and place it in the source tree at the directory that contains the topmost package directories. In this location, no path is needed when documenting packages, since -sourcepath will point to this file. For example, if the source tree for the java.lang package is /src/classes/java/lang/, then you could place the overview file at /src/classes/overview.html. See Real World Example. For information about the file specified by path/filename, see overview comment file. Note that the overview page is created only if you pass into javadoc two or more package names. For further explanation, see HTML 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 is the 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 doclet command line options.
-doclet  class Specifies the class file that starts the doclet used in generating the documentation. Use the fully-qualified name. This doclet defines the content and formats the output. If the -doclet option is not used, javadoc uses the standard doclet for generating the default HTML format. This class must contain the start(Root) method. The path to this starting class is defined by the -docletpath option. For example, to call the MIF doclet, use: -doclet com.sun.tools.doclets.mif.MIFDoclet For full, working examples of running a particular doclet, see the MIF Doclet documentation @ http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
-docletpath  classpathlist Specifies the path to the doclet starting class file (specified with the -doclet option) and any jar files it depends on. If the starting class file is in a jar file, then this specifies the path to that jar file, as shown in the example below. You can specify an absolute path or a path relative to the current directory. If classpathlist contains multiple paths or jar files, they should be separated with a colon (:) on Solaris and a semi-colon (;) on Windows. This option is not necessary if the doclet starting class is already in the search path. Example of path to jar file that contains the starting doclet class file. Notice the jar filename is included. -docletpath /home/user/mifdoclet/lib/mifdoclet.jar Example of path to starting doclet class file. Notice the class filename is omitted. -docletpath /home/user/mifdoclet/classes/com/sun/tools/doclets/mif/ For full, working examples of running a particular doclet, see the MIF Doclet documentation @ http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
-1.1 This feature has been removed from Javadoc 1.4. There is no replacement for it. This option created documentation with the appearance and functionality of documentation generated by Javadoc 1.1 (it never supported nested classes). If you need this option, use Javadoc 1.2 or 1.3 instead.
o 1.5 - javadoc accepts code containing generics and other language features introduced in JDK 1.5. The compiler defaults to the 1.5 behavior if the -source flag is not used.
o 1.4 - javadoc accepts code containing assertions, which were introduced in JDK 1.4.
o 1.3 - javadoc does not support assertions, generics, or other language features introduced after JDK 1.3. Use the value of release corresponding to that used when compiling the code with javac.
-sourcepath  sourcepathlist Specifies the search paths for finding source files (.java) when passing package names or -subpackages into the javadoc command. The sourcepathlist can contain multiple paths by separating them with a colon (:). The Javadoc tool will search in all subdirectories of the specified paths. Note that this option is not only used to locate the source files being documented, but also to find source files that are not being documented but whose comments are inherited by the source files being documented. Note that you can use the -sourcepath option only when passing package names into the javadoc command -- it will not locate .java files passed into the javadoc command. (To locate .java files, cd to that directory or include the path ahead of each file, as shown at Documenting One or More Classes.) If -sourcepath is omitted, javadoc uses the class path to find the source files (see -classpath). Therefore, the default -sourcepath is the value of class path. If -classpath is omitted and you are passing package names into javadoc, it looks in the current directory (and subdirectories) for the source files. Set sourcepathlist to the root directory of the source tree for the package you are documenting. For example, suppose you want to document a package called com.mypackage whose source files are located at: /home/user/src/com/mypackage/*.java In this case you would specify the sourcepath to /home/user/src, the directory that contains com/mypackage, and then supply the package name com.mypackage: % javadoc -sourcepath /home/user/src/ com.mypackage This is easy to remember by noticing that if you concatenate the value of sourcepath and the package name together and change the dot 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 for referenced classes (.class files) -- these are the documented classes plus any classes referenced by those classes. The classpathlist can contain multiple paths by separating them with a colon (:). The Javadoc tool will search in all subdirectories of the specified paths. Follow the instructions in class path @ http://docs.oracle.com/javase/7/docs/technotes/tools/index.html#general documentation for specifying classpathlist. If -sourcepath is omitted, the Javadoc tool uses -classpath to find the source files as well as class files (for backward compatibility). Therefore, if you want to search for source and class files in separate paths, use both -sourcepath and -classpath. For example, if you want to document com.mypackage, whose source files reside in the directory /home/user/src/com/mypackage, and if this package relies on a library in /home/user/lib, you would specify: % 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 is set. If both are not set, the Javadoc tool searches for classes from the current directory. For an in-depth description of how the Javadoc tool uses -classpath to find user classes as it relates to extension classes and bootstrap classes, see How Classes Are Found @ http://docs.oracle.com/javase/7/docs/technotes/tools/findingclasses.html. As a special convenience, a class path element containing a basename of * is considered equivalent to specifying a list of all the files in the directory with the extension .jar or .JAR (a Java program cannot tell the difference between the two invocations). For example, if directory foo contains a.jar and b.JAR, then the class path element foo/* is expanded to a A.jar:b.JAR, except that the order of jar files is unspecified. All jar files in the specified directory, even hidden ones, are included in the list. A classpath entry consisting simply of * expands to a list of all the jar files in the current directory. The CLASSPATH environment variable, where defined, will be similarly expanded. Any classpath wildcard expansion occurs before the Java virtual machine is started -- no Java program will ever see unexpanded wildcards except by querying the environment. For example; by invoking System.getenv("CLASSPATH").
-subpackages  package1:package2:... Generates documentation from source files in the specified packages and recursively in their subpackages. This option is useful when adding new subpackages to the source code, as they are automatically included. Each package argument is any top-level subpackage (such as java) or fully qualified package (such as javax.swing) that does not need to contain source files. Arguments are separated by colons (on all operating systmes). Wildcards are not needed or allowed. Use -sourcepath to specify where to find the packages. This option is smart about not processing source files that are in the source tree but do not belong to the packages, as described at processing 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 specific packages.
-exclude  packagename1:packagename2:... Unconditionally excludes the specified packages and their subpackages from the list formed by -subpackages. It excludes those packages even if they would otherwise be included by some previous or later -subpackages option. For example: % javadoc -sourcepath /home/user/src -subpackages java -exclude java.net:java.lang would include java.io, java.util, and java.math (among others), but would exclude packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a subpackage of java.lang).
-bootclasspath  classpathlist Specifies the paths where the boot classes reside. These are nominally the Java platform classes. The bootclasspath is part of the search path the Javadoc tool will use to look up source and class files. See How Classes Are Found @ http://docs.oracle.com/javase/7/docs/technotes/tools/findingclasses.html#srcfiles. for more details. Separate directories in classpathlist with colons (:).
-extdirs  dirlist Specifies the directories where extension classes reside. These are any classes that use the Java Extension mechanism. The extdirs is part of the search path the Javadoc tool will use to look up source and class files. See -classpath (above) for more details. Separate directories in dirlist with colons (:).
-verbose Provides more detailed messages while javadoc is running. Without the verbose option, messages appear for loading the source files, generating the documentation (one message per source file), and sorting. The verbose option causes the printing of additional messages specifying the number of milliseconds to parse each java source file.
-quiet Shuts off non-error and non-warning messages, leaving only the warnings and errors appear, making them easier to view. Also suppresses the version string.
-breakiterator Uses the internationalized sentence boundary of java.text.BreakIterator @ http://docs.oracle.com/javase/7/docs/api/java/text/BreakIterator.html to determine the end of the first sentence for English (all other locales already use BreakIterator), rather than an English language, locale-specific algorithm. By first sentence, we mean the first sentence in the main description of a package, class or member. This sentence is copied to the package, class or member summary, and to the alphabetic index. From JDK 1.2 forward, the BreakIterator class is already used to determine the end of sentence for all languages but English. Therefore, the -breakiterator option has no effect except for English from 1.2 forward. English has its own default algorithm:
o English default sentence-break algorithm - Stops at a period followed by a space or a HTML block tag, such as <P>.
o Breakiterator sentence-break algorithm - In general, stops at a period, question mark or exclamation mark followed by a space if the next word starts with a capital letter. This is meant to handle most abbreviations (such as "The serial no. is valid", but won't handle "Mr. Smith"). Doesn't stop at HTML tags or sentences that begin 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 warning messages that were in 1.4.x and have left the default sentence-break algorithm unchanged. That is, the -breakiterator option is not the default in 1.5.0, nor do we expect it to become the default. This is a reversal from our former intention that the default would change in the "next major release" (1.5.0). This means if you have not modified your source code to eliminate the breakiterator warnings in 1.4.x, then you don't have to do anything, and the warnings go away starting with 1.5.0. The reason for this reversal is because any benefit to having breakiterator become the default would be outweighed by the incompatible source change it would require. We regret any extra work and confusion this has caused.
-locale  language_country_variant Important - The -locale option must be placed ahead (to the left) of any options provided by the standard doclet or any other doclet. Otherwise, the navigation bars will appear in English. This is the only command-line option that is order-dependent. Specifies the locale that javadoc uses when generating documentation. The argument is the name of the locale, as described in java.util.Locale documentation, such as en_US (English, United States) or en_US_WIN (Windows variant). Specifying a locale causes javadoc to choose the resource files of that locale for messages (strings in the navigation bar, headings for lists and tables, help file contents, comments in stylesheet.css, and so forth). It also specifies the sorting order for lists sorted alphabetically, and the sentence separator to determine the end of the first sentence. It does not determine the locale of the doc comment text specified in the source files of the documented classes.
-encoding  name Specifies the encoding name of the source files, such as EUCJIS/SJIS. If this option is not specified, the platform default converter is used. Also see -docencoding and -charset.
-Jflag Passes flag directly to the runtime system java that runs javadoc. Notice there must be no space between the J and the flag. For example, if you need to ensure that the system sets aside 32 megabytes of memory in which to process the generated documentation, then you would call the -Xmx option of java as follows (-Xms is optional, as it only sets the size of initial memory, which is useful if you know the minimum amount of memory required): % javadoc -J-Xmx32m -J-Xms32m com.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 the standard doclet appears in its output stream.)
Options Provided by the Standard Doclet -d  directory Specifies the destination directory where javadoc saves the generated HTML files. (The "d" means "destination.") Omitting this option causes the files to be saved to the current directory. The value directory can be absolute, or relative to the current working directory. As of 1.4, the destination directory is automatically created when javadoc is run. For example, the following generates the documentation for the package com.mypackage and saves the results in the /home/user/doc/ directory: % javadoc -d /home/user/doc com.mypackage