--- a/jdk/src/linux/doc/man/javadoc.1 Thu Apr 30 15:04:39 2009 -0700
+++ b/jdk/src/linux/doc/man/javadoc.1 Mon May 04 18:28:26 2009 -0700
@@ -1,6 +1,4 @@
-.'" t
-."
-." Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
+." Copyright 2002-2006 Sun Microsystems, Inc. All Rights Reserved.
." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
."
." This code is free software; you can redistribute it and/or modify it
@@ -21,10 +19,9 @@
." CA 95054 USA or visit www.sun.com if you need additional information or
." have any questions.
."
-." `
-.TH javadoc 1 "07 Aug 2006"
-." Generated by html2man
-.SH NAME
+.TH javadoc 1 "04 May 2009"
+." Generated from HTML by html2man (author: Eric Armstrong)
+.SH "Name"
javadoc \- The Java API Documentation Generator
.RS 3
@@ -153,7 +150,11 @@
In many cases, the Javadoc tool allows you to generate documentation for source files whose code is incomplete or erroneous. This is a benefit that enables you to generate documentation before all debugging and troubleshooting is done. For example, according to the \f2Java Language Specification\fP, a class that contains an abstract method should itself be declared abstract. The Javadoc tool does not check for this, and would proceed without a warning, whereas the javac compiler stops on this error. The Javadoc tool does do some primitive checking of doc comments. Use the DocCheck doclet to check the doc comments more thoroughly.
.LP
.LP
-When the Javadoc tool builds its internal structure for the documentation, 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 more about this, see How Classes Are Found. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool's class path.
+When the Javadoc tool builds its internal structure for the documentation, 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 more about this, see
+.na
+\f2How Classes Are Found\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool's class path.
.LP
.SS
Javadoc Doclets
@@ -164,7 +165,10 @@
.RS 3
.TP 2
o
-Javadoc Doclets
+.na
+\f2Javadoc Doclets\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html
.TP 2
o
The \f2\-doclet\fP command\-line option
@@ -180,7 +184,10 @@
.RS 3
.TP 2
o
-Javadoc Enhancements for details about improvements added in Javadoc.
+.na
+\f2Javadoc Enhancements\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/guides/javadoc/index.html for details about improvements added in Javadoc.
.TP 2
o
.na
@@ -198,7 +205,7 @@
.na
\f2Requirements for Writing API Specifications\fP @
.fi
-http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Standard requirements used when writing the Java 2 Platform Specification. It can be useful whether you are writing API specifications in source file documentation comments or in other formats. It covers requirements for packages, classes, interfaces, fields and methods to satisfy testable assertions.
+http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Standard requirements used when writing the Java SE Platform Specification. It can be useful whether you are writing API specifications in source file documentation comments or in other formats. It covers requirements for packages, classes, interfaces, fields and methods to satisfy testable assertions.
.TP 2
o
.na
@@ -284,7 +291,7 @@
.RS 3
.TP 2
o
-\f2package\-info.java\fP \- Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is new in JDK 5.0, and is preferred over package.html.
+\f2package\-info.java\fP \- Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is generally preferred over package.html.
.TP 2
o
\f2package.html\fP \- Can contain only package comments and Javadoc tags, no package annotations.
@@ -295,7 +302,7 @@
A package may have a single \f2package.html\fP file or a single \f2package\-info.java\fP file but not both. Place either file in the package directory in the source tree along with your \f2.java\fP files.
.LP
.LP
-\f4package\-info.java\fP This file can contain a package comment of the following structure \-\- the comment is placed before the package declaration:
+\f4package\-info.java\fP \- This file can contain a package comment of the following structure \-\- the comment is placed before the package declaration:
.LP
.LP
File: \f2java/applet/package\-info.java\fP
@@ -388,7 +395,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 326 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 353 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -522,7 +529,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 379 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 406 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -580,10 +587,18 @@
Processes any package tags that are present.
.TP 2
o
-Inserts the processed text at the bottom of the package summary page it generates, as shown in Package Summary.
+Inserts the processed text at the bottom of the package summary page it generates, as shown in
+.na
+\f2Package Summary\fP @
+.fi
+http://java.sun.com/javase/6/docs/api/java/applet/package\-summary.html.
.TP 2
o
-Copies the first sentence of the package comment to the top of the package summary page. It also adds the package name and this first sentence to the list of packages on the overview page, as shown in Overview Summary. The end\-of\-sentence is determined by the same rules used for the end of the first sentence of class and member main descriptions.
+Copies the first sentence of the package comment to the top of the package summary page. It also adds the package name and this first sentence to the list of packages on the overview page, as shown in
+.na
+\f2Overview Summary\fP @
+.fi
+http://java.sun.com/javase/6/docs/api/overview\-summary.html. The end\-of\-sentence is determined by the same rules used for the end of the first sentence of class and member main descriptions.
.RE
.LP
@@ -614,7 +629,11 @@
Processes any overview tags that are present.
.TP 2
o
-Inserts the processed text at the bottom of the overview page it generates, as shown in Overview Summary.
+Inserts the processed text at the bottom of the overview page it generates, as shown in
+.na
+\f2Overview Summary\fP @
+.fi
+http://java.sun.com/javase/6/docs/api/overview\-summary.html.
.TP 2
o
Copies the first sentence of the overview comment to the top of the overview summary page.
@@ -907,7 +926,7 @@
.LP
.SS
-a name="generatedapideclarations"/> Generated API Declarations
+Generated API Declarations
.LP
.LP
The Javadoc tool generates a declaration at the start of each class, interface, field, constructor, and method description for that API item. For example, the declaration for the \f2Boolean\fP class is:
@@ -1332,7 +1351,7 @@
.nr 41 \n(80+(3*\n(38)
.nr 81 +\n(41
.nr TW \n(81
-.if t .if \n(TW>\n(.li .tm Table at line 1084 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 1123 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -1455,19 +1474,30 @@
.LP
.LP
-Note: Starting with JDK 5.0, you can deprecate a program element using the @Deprecated annotation.
+Note: You can deprecate a program element using the
+.na
+\f2@Deprecated annotation\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/deprecation.html.
.LP
.RE
-.LP
-Adds a comment indicating that this API should no longer be used (even though it may continue to work). The Javadoc tool moves the \f2deprecated\-text\fP 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.
-.LP
-The first sentence of \f2deprecated\-text\fP 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 \f2{@link}\fP tag (for Javadoc 1.2 or later) that points to the replacement API:
+.RE
+.RS 3
+
+.LP
+.LP
+Adds a comment indicating that this API should no longer be used (even though it may continue to work). The Javadoc tool moves the \f2deprecated\-text\fP 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.
+.LP
+.LP
+The first sentence of \f2deprecated\-text\fP 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 \f2{@link}\fP tag (for Javadoc 1.2 or later) that points to the replacement API:
+.LP
.LP
For more details, see
.na
\f2writing @deprecated tags\fP @
.fi
-http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@deprecated.
+http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@deprecated.
+.LP
.RS 3
.TP 2
o
@@ -1481,15 +1511,28 @@
.fl
*/
.fl
+
+.fl
\fP
.fi
.TP 2
o
For Javadoc 1.1, the standard format is to create a \f2@see\fP tag (which cannot be in\-line) for each \f2@deprecated\fP tag.
.RE
-.LP
-For more about deprecation, see The @deprecated tag.
-.LP
+
+.LP
+.LP
+For more about deprecation, see
+.na
+\f2The @deprecated tag\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/guides/javadoc/deprecation/index.html.
+.LP
+.LP
+
+.LP
+.RE
+.RS 3
.TP 3
{@code\ text}
Equivalent to \f2<code>{@literal}</code>\fP.
@@ -1500,16 +1543,22 @@
.fl
\fP\f4{@code A<B>C}\fP\f3
.fl
+
+.fl
\fP
.fi
+.LP
displays in the generated HTML page unchanged, as:
.nf
\f3
.fl
\fP\f4A<B>C\fP\f3
.fl
+
+.fl
\fP
.fi
+.LP
The noteworthy point is that the \f2<B>\fP is not interpreted as bold and is in code font.
.LP
If you want the same functionality without the code font, use \f2{@literal}\fP.
@@ -1528,9 +1577,12 @@
.fl
javadoc \-bottom '<a href="{@docRoot}/copyright.html">Copyright</a>'
.fl
+
+.fl
\fP
.fi
-NOTE \- When using \f2{@docRoot}\fP 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: \f2{{@docRoot}}\fP. It also requires double (rather than single) quotes to enclose arguments to options such as \f2\-bottom\fP (with the quotes around the \f2href\fP argument omitted).
+.LP
+NOTE \- When using \f2{@docRoot}\fP 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: \f2{{@docRoot}}\fP. It also requires double (rather than single) quotes to enclose arguments to options such as \f2\-bottom\fP (with the quotes around the \f2href\fP argument omitted).
.TP 3
2.
In a doc comment:
@@ -1543,31 +1595,42 @@
.fl
*/
.fl
+
+.fl
\fP
.fi
.RE
+.LP
The reason this tag is needed is because the generated docs are in hierarchical directories, as deep as the number of subpackages. This expression:
.nf
\f3
.fl
<a href="{@docRoot}/copyright.html">
.fl
+
+.fl
\fP
.fi
+.LP
would resolve to:
.nf
\f3
.fl
<a href="../../copyright.html"> for java/lang/Object.java
.fl
+
+.fl
\fP
.fi
+.LP
and
.nf
\f3
.fl
<a href="../../../copyright.html"> for java/lang/ref/Reference.java
.fl
+
+.fl
\fP
.fi
.LP
@@ -1605,24 +1668,33 @@
.fl
Use the {@link #getComponentAt(int, int) getComponentAt} method.
.fl
+
+.fl
\fP
.fi
+.LP
From this, the standard doclet would generate the following HTML (assuming it refers to another class in the same package):
.nf
\f3
.fl
Use the <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> method.
.fl
+
+.fl
\fP
.fi
+.LP
Which appears on the web page as:
.nf
\f3
.fl
Use the getComponentAt method.
.fl
+
+.fl
\fP
.fi
+.LP
You can extend \f2{@link}\fP to link to classes not being documented by using the \f2\-link\fP option.
.LP
For more details, see
@@ -1639,14 +1711,20 @@
.fl
Refer to {@linkplain add() the overridden method}.
.fl
+
+.fl
\fP
.fi
+.LP
This would display as:
.RS 3
+
+.LP
.LP
Refer to the overridden method.
.LP
.RE
+.LP
.TP 3
{@literal\ text}
Displays \f2text\fP without interpreting the text as HTML markup or nested javadoc tags. This enables you to use regular angle brackets (\f2<\fP and \f2>\fP) instead of the HTML entities (\f2<\fP and \f2>\fP) in doc comments, such as in parameter types (\f2<Object>\fP), inequalities (\f23 < 4\fP), or arrows (\f2<\-\fP). For example, the doc comment text:
@@ -1655,11 +1733,16 @@
.fl
\fP\f4{@literal A<B>C}\fP\f3
.fl
+
+.fl
\fP
.fi
+.LP
displays unchanged in the generated HTML page in your browser, as:
.LP
-\f2\ \ \ \ \ \fPA<B>C The noteworthy point is that the \f2<B>\fP is not interpreted as bold (and it is not in code font).
+\f2\ \ \ \ \ \fPA<B>C
+.LP
+The noteworthy point is that the \f2<B>\fP is not interpreted as bold (and it is not in code font).
.LP
If you want the same functionality but with the text in code font, use \f2{@code}\fP.
.LP
@@ -1683,6 +1766,8 @@
.fl
}
.fl
+
+.fl
\fP
.fi
.LP
@@ -1706,8 +1791,11 @@
.fl
}
.fl
+
+.fl
\fP
.fi
+.LP
For more details, see
.na
\f2writing @param tags\fP @
@@ -1736,15 +1824,26 @@
.fl
@see "The Java Programming Language"
.fl
+
+.fl
\fP
.fi
-This generates text such as:
+.LP
+This generates text such as:
+.RE
+.RE
+.RS 3
+.RS 3
+.RS 3
+
+.LP
.RS 3
.RS 3
.TP 3
See Also:
"The Java Programming Language"
.RE
+.RE
.LP
.RE
@@ -1981,7 +2080,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 1547 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 1666 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -2327,7 +2426,7 @@
.nr 42 \n(81+(3*\n(38)
.nr 82 +\n(42
.nr TW \n(82
-.if t .if \n(TW>\n(.li .tm Table at line 1623 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 1742 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -2502,6 +2601,14 @@
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@see.
.RE
+.RE
+.RS 3
+
+.LP
+.LP
+
+.LP
+.RS 3
.TP 3
@serial\ field\-description | include | exclude
Used in the doc comment for a default serializable field.
@@ -2524,7 +2631,11 @@
.LP
The tag @serial at a class level overrides @serial at a package level.
.LP
-For more information about how to use these tags, along with an example, see "Documenting Serializable Fields and Data for a Class," Section 1.6 of the \f2Java Object Serialization Specification\fP. Also see the
+For more information about how to use these tags, along with an example, see "
+.na
+\f2Documenting Serializable Fields and Data for a Class\fP @
+.fi
+http://java.sun.com/javase/6/docs/platform/serialization/spec/serial\-arch.html," Section 1.6 of the \f2Java Object Serialization Specification\fP. Also see the
.na
\f2Serialization FAQ\fP @
.fi
@@ -2552,8 +2663,11 @@
.fl
@since 1.5
.fl
+
+.fl
\fP
.fi
+.LP
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.
.LP
.TP 3
@@ -2584,8 +2698,11 @@
.fl
public static final String SCRIPT_START = "<script>"
.fl
+
+.fl
\fP
.fi
+.LP
When used with argument \f2package.class#field\fP in any doc comment, it displays the value of the specified constant:
.nf
\f3
@@ -2600,11 +2717,18 @@
.fl
}
.fl
+
+.fl
\fP
.fi
+.LP
The argument \f2package.class#field\fP takes a form identical to that of the @see argument, except that the member must be a static field.
.LP
-These values of these constants are also displayed on the Constant Field Values page.
+These values of these constants are also displayed on the
+.na
+\f2Constant Field Values\fP @
+.fi
+http://java.sun.com/javase/6/docs/api/constant\-values.html page.
.LP
.TP 3
@version\ version\-text
@@ -2618,6 +2742,9 @@
.fi
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#@version.
.RE
+
+.LP
+.RE
.SS
Where Tags Can Be Used
.LP
@@ -2702,7 +2829,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 1816 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 1963 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -2819,7 +2946,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 1848 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 1995 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -2938,7 +3065,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 1882 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 2029 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -3098,7 +3225,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 1957 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 2104 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -3242,7 +3369,7 @@
.nr 40 \n(79+(0*\n(38)
.nr 80 +\n(40
.nr TW \n(80
-.if t .if \n(TW>\n(.li .tm Table at line 2016 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 2163 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -3325,6 +3452,8 @@
.LP
.SH "OPTIONS"
.LP
+
+.LP
.LP
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.
.LP
@@ -3545,7 +3674,7 @@
.nr 42 \n(81+(3*\n(38)
.nr 82 +\n(42
.nr TW \n(82
-.if t .if \n(TW>\n(.li .tm Table at line 2192 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 2341 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -3657,11 +3786,11 @@
\fP
.fi
.LP
-For full, working examples of running a particular doclet, see
+For full, working examples of running a particular doclet, see the
.na
-\f2Running the MIF Doclet\fP @
+\f2MIF Doclet documentation\fP @
.fi
-http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet.
+http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
.LP
.TP 3
\-docletpath\ classpathlist
@@ -3683,11 +3812,11 @@
.fl
\fP
.fi
-For full, working examples of running a particular doclet, see
+For full, working examples of running a particular doclet, see the
.na
-\f2Running the MIF Doclet\fP @
+\f2MIF Doclet documentation\fP @
.fi
-http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet.
+http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
.LP
.TP 3
\-1.1
@@ -3808,7 +3937,7 @@
.nr 41 \n(80+(3*\n(38)
.nr 81 +\n(41
.nr TW \n(81
-.if t .if \n(TW>\n(.li .tm Table at line 2302 file Input is too wide - \n(TW units
+.if t .if \n(TW>\n(.li .tm Table at line 2451 file Input is too wide - \n(TW units
.fc
.nr #T 0-1
.nr #a 0-1
@@ -3915,7 +4044,11 @@
.LP
.TP 3
\-classpath\ classpathlist
-Specifies the paths where javadoc will look for referenced classes (\f2.class\fP files) \-\- these are the documented classes plus any classes referenced by those classes. The \f2classpathlist\fP can contain multiple paths by separating them with a colon (\f2:\fP). The Javadoc tool will search in all subdirectories of the specified paths. Follow the instructions in class path documentation for specifying \f2classpathlist\fP.
+Specifies the paths where javadoc will look for referenced classes (\f2.class\fP files) \-\- these are the documented classes plus any classes referenced by those classes. The \f2classpathlist\fP can contain multiple paths by separating them with a colon (\f2:\fP). The Javadoc tool will search in all subdirectories of the specified paths. Follow the instructions in
+.na
+\f2class path\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/tools/index.html#general documentation for specifying \f2classpathlist\fP.
.LP
If \f2\-sourcepath\fP is omitted, the Javadoc tool uses \f2\-classpath\fP 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 \f2\-sourcepath\fP and \f2\-classpath\fP.
.LP
@@ -3928,7 +4061,11 @@
.fi
As with other tools, if you do not specify \f2\-classpath\fP, 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.
.LP
-For an in\-depth description of how the Javadoc tool uses \f2\-classpath\fP to find user classes as it relates to extension classes and bootstrap classes, see How Classes Are Found.
+For an in\-depth description of how the Javadoc tool uses \f2\-classpath\fP to find user classes as it relates to extension classes and bootstrap classes, see
+.na
+\f2How Classes Are Found\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html.
.LP
As a special convenience, a class path element containing a basename of \f2*\fP is considered equivalent to specifying a list of all the files in the directory with the extension \f2.jar\fP or \f2.JAR\fP (a java program cannot tell the difference between the two invocations).
.br
@@ -3963,7 +4100,11 @@
.LP
.TP 3
\-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. for more details. Separate directories in \f2classpathlist\fP with colons (:).
+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
+.na
+\f2How Classes Are Found\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfiles. for more details. Separate directories in \f2classpathlist\fP with colons (:).
.LP
.TP 3
\-extdirs\ dirlist
@@ -3979,7 +4120,11 @@
.LP
.TP 3
\-breakiterator\
-Uses the internationalized sentence boundary of \f2java.text.BreakIterator\fP to determine the end of the first sentence for English (all other locales already use \f2BreakIterator\fP), rather than an English language, locale\-specific algorithm. By \f2first sentence\fP, 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.
+Uses the internationalized sentence boundary of
+.na
+\f2java.text.BreakIterator\fP @
+.fi
+http://java.sun.com/javase/6/docs/api/java/text/BreakIterator.html to determine the end of the first sentence for English (all other locales already use \f2BreakIterator\fP), rather than an English language, locale\-specific algorithm. By \f2first sentence\fP, 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.
.LP
From JDK 1.2 forward, the BreakIterator class is already used to determine the end of sentence for all languages but English. Therefore, the \f2\-breakiterator\fP option has no effect except for English from 1.2 forward. English has its own default algorithm:
.RS 3
@@ -4057,7 +4202,7 @@
\-use
Includes one "Use" page for each documented class and package. The page describes what packages, classes, methods, constructors and fields use any API of the given class or package. Given class C, things that use class C would include subclasses of C, fields declared as C, methods that return C, and methods and constructors with parameters of type C.
.LP
-For example, let's look at what might appear on the "Use" page for String. The \f2getName()\fP method in the \f2java.awt.Font\fP class returns type \f2String\fP. Therefore, \f2getName()\fP uses \f2String\fP, and you will find that method on the "Use" page for \f2String\fP.
+For example, let us look at what might appear on the "Use" page for String. The \f2getName()\fP method in the \f2java.awt.Font\fP class returns type \f2String\fP. Therefore, \f2getName()\fP uses \f2String\fP, and you will find that method on the "Use" page for \f2String\fP.
.LP
Note that this documents only uses of the API, not the implementation. If a method uses \f2String\fP in its implementation but does not take a string as an argument or return a string, that is not considered a "use" of \f2String\fP.
.LP
@@ -4080,7 +4225,7 @@
.nf
\f3
.fl
- % \fP\f3javadoc \-windowtitle "Java 2 Platform" com.mypackage\fP
+ % \fP\f3javadoc \-windowtitle "Java SE Platform" com.mypackage\fP
.fl
.fi
.TP 3
@@ -4089,7 +4234,7 @@
.nf
\f3
.fl
- % \fP\f3javadoc \-doctitle "Java<sup><font size=\\"\-2\\">TM</font></sup>" com.mypackage\fP
+ % \fP\f3javadoc \-doctitle "Java(TM)" com.mypackage\fP
.fl
.fi
.TP 3
@@ -4163,18 +4308,18 @@
when using an absolute URL to the external API document, if your shell \f2does not allow\fP a program to open a connection to that URL for reading. This can occur if you are behind a firewall and the document you want to link to is on the other side.
.RE
.LP
-\f3Example using absolute links to the external docs\fP \- Let's say you want to link to the \f2java.lang\fP, \f2java.io\fP and other Java 2 Platform packages at
+\f3Example using absolute links to the external docs\fP \- Let us say you want to link to the \f2java.lang\fP, \f2java.io\fP and other Java Platform packages at
.na
-\f2http://java.sun.com/j2se/1.5.0/docs/api\fP @
+\f2http://java.sun.com/javase/6/docs/api/\fP @
.fi
-http://java.sun.com/j2se/1.5.0/docs/api, The following command generates documentation for the package \f2com.mypackage\fP with links to the Java 2 Platform packages. The generated documentation will contain links to the \f2Object\fP class, for example, in the class trees. (Other options, such as \f2\-sourcepath\fP and \f2\-d\fP, are not shown.)
+http://java.sun.com/javase/6/docs/api. The following command generates documentation for the package \f2com.mypackage\fP with links to the Java SE Platform packages. The generated documentation will contain links to the \f2Object\fP class, for example, in the class trees. (Other options, such as \f2\-sourcepath\fP and \f2\-d\fP, are not shown.)
.nf
\f3
.fl
- % \fP\f3javadoc \-link http://java.sun.com/j2se/1.5.0/docs/api com.mypackage\fP
+ % \fP\f3javadoc \-link http://java.sun.com/javase/6/docs/api com.mypackage\fP
.fl
.fi
-\f3Example using relative links to the external docs\fP \- Let's say you have two packages whose docs are generated in different runs of the Javadoc tool, and those docs are separated by a relative path. In this example, the packages are \f2com.apipackage\fP, an API, and \f2com.spipackage\fP, an SPI (Service Provide Interface). You want the documentation to reside in \f2docs/api/com/apipackage\fP and \f2docs/spi/com/spipackage\fP. Assuming the API package documentation is already generated, and that \f2docs\fP is the current directory, you would document the SPI package with links to the API documentation by running:
+\f3Example using relative links to the external docs\fP \- Let us say you have two packages whose docs are generated in different runs of the Javadoc tool, and those docs are separated by a relative path. In this example, the packages are \f2com.apipackage\fP, an API, and \f2com.spipackage\fP, an SPI (Service Provide Interface). You want the documentation to reside in \f2docs/api/com/apipackage\fP and \f2docs/spi/com/spipackage\fP. Assuming the API package documentation is already generated, and that \f2docs\fP is the current directory, you would document the SPI package with links to the API documentation by running:
.nf
\f3
.fl
@@ -4214,11 +4359,11 @@
.LP
\f3Package List\fP \- The \f2\-link\fP option requires that a file named \f2package\-list\fP, which is generated by the Javadoc tool, exist at the URL you specify with \f2\-link\fP. The \f2package\-list\fP file is a simple text file that lists the names of packages documented at that location. In the earlier example, the Javadoc tool looks for a file named \f2package\-list\fP at the given URL, reads in the package names and then links to those packages at that URL.
.LP
-For example, the package list for the Java 2 Platform 5.0 API is located at
+For example, the package list for the Java SE 6 API is located at
.na
-\f2http://java.sun.com/j2se/1.5.0/docs/api/package\-list\fP @
+\f2http://java.sun.com/javase/6/docs/api/package\-list\fP @
.fi
-http://java.sun.com/j2se/1.5.0/docs/api/package\-list. and starts out as follows:
+http://java.sun.com/javase/6/docs/api/package\-list. and starts as follows:
.nf
\f3
.fl
@@ -4277,15 +4422,15 @@
.LP
You can specify multiple \f2\-linkoffline\fP options in a given javadoc run. (Prior to 1.2.2, it could be specified only once.)
.LP
-\f3Example using absolute links to the external docs\fP \- Let's say you want to link to the \f2java.lang\fP, \f2java.io\fP and other Java 2 Platform packages at \f2http://java.sun.com/j2se/1.5.0/docs/api\fP, but your shell does not have web access. You could open the \f2package\-list\fP file in a browser at
+\f3Example using absolute links to the external docs\fP \- Let us say you want to link to the \f2java.lang\fP, \f2java.io\fP and other Java SE Platform packages at \f2http://java.sun.com/javase/6/docs/api\fP, but your shell does not have web access. You could open the \f2package\-list\fP file in a browser at
.na
-\f2http://java.sun.com/j2se/1.5.0/docs/api/package\-list\fP @
+\f2http://java.sun.com/javase/6/docs/api/package\-list\fP @
.fi
-http://java.sun.com/j2se/1.5.0/docs/api/package\-list, save it to a local directory, and point to this local copy with the second argument, \f2packagelistLoc\fP. In this example, the package list file has been saved to the current directory "\f2.\fP" . The following command generates documentation for the package \f2com.mypackage\fP with links to the Java 2 Platform packages. The generated documentation will contain links to the \f2Object\fP class, for example, in the class trees. (Other necessary options, such as \f2\-sourcepath\fP, are not shown.)
+http://java.sun.com/javase/6/docs/api/package\-list, save it to a local directory, and point to this local copy with the second argument, \f2packagelistLoc\fP. In this example, the package list file has been saved to the current directory "\f2.\fP" . The following command generates documentation for the package \f2com.mypackage\fP with links to the Java SE Platform packages. The generated documentation will contain links to the \f2Object\fP class, for example, in the class trees. (Other necessary options, such as \f2\-sourcepath\fP, are not shown.)
.nf
\f3
.fl
-% \fP\f3javadoc \-linkoffline http://java.sun.com/j2se/1.5.0/docs/api . com.mypackage\fP
+% \fP\f3javadoc \-linkoffline http://java.sun.com/javase/6/docs/api . com.mypackage\fP
.fl
.fi
.LP
@@ -4303,7 +4448,7 @@
.LP
\f3Updating docs\fP \- Another use for \f2\-linkoffline\fP option is useful if your project has dozens or hundreds of packages, if you have already run javadoc on the entire tree, and now, in a separate run, you want to quickly make some small changes and re\-run javadoc on just a small portion of the source tree. This is somewhat of a hack in that it works properly only if your changes are only to doc comments and not to declarations. If you were to add, remove or change any declarations from the source code, then broken links could show up in the index, package tree, inherited member lists, use page, and other places.
.LP
-First, you create a new destination directory (call it \f2update\fP) for this new small run. Let's say the original destination directory was named \f2html\fP. In the simplest example, cd to the parent of \f2html\fP. Set the first argument of \f2\-linkoffline\fP to the current directory "." and set the second argument to the relative path to \f2html\fP, where it can find \f2package\-list\fP, and pass in only the package names of the packages you want to update:
+First, you create a new destination directory (call it \f2update\fP) for this new small run. Let us say the original destination directory was named \f2html\fP. In the simplest example, cd to the parent of \f2html\fP. Set the first argument of \f2\-linkoffline\fP to the current directory "." and set the second argument to the relative path to \f2html\fP, where it can find \f2package\-list\fP, and pass in only the package names of the packages you want to update:
.nf
\f3
.fl
@@ -4527,7 +4672,7 @@
.br
\f4f\fP (fields)
.LP
-\f3Examples of single tags\fP \- An example of a tag option for a tag that that can be used anywhere in the source code is:
+\f3Examples of single tags\fP \- An example of a tag option for a tag that can be used anywhere in the source code is:
.nf
\f3
.fl
@@ -4635,7 +4780,10 @@
.RS 3
.TP 2
o
-Taglet Overview
+.na
+\f2Taglet Overview\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/guides/javadoc/taglet/overview.html
.RE
.LP
Taglets are useful for block or inline tags. They can have any number of arguments and implement custom behavior, such as making text bold, formatting bullets, writing out the text to a file, or starting other processes.
@@ -4713,7 +4861,7 @@
.nf
\f3
.fl
- <!\-\- Generated by javadoc (build 1.5.0\-internal) on Tue Jun 22 09:57:24 PDT 2004 \-\->
+ <!\-\- Generated by javadoc (build 1.5.0_01) on Thu Apr 02 14:04:52 IST 2009 \-\->
.fl
\fP
.fi
@@ -4724,6 +4872,8 @@
.RE
.SH "COMMAND LINE ARGUMENT FILES"
.LP
+
+.LP
.LP
To shorten or simplify the javadoc command line, you can specify one or more files that themselves contain arguments to the \f2javadoc\fP command (except \f2\-J\fP options). This enables you to create javadoc commands of any length on any operating system.
.LP
@@ -4771,19 +4921,19 @@
.fl
\-splitindex
.fl
- \-windowtitle 'Java 2 Platform v1.3 API Specification'
-.fl
- \-doctitle 'Java<sup><font size="\-2">TM</font></sup> 2 Platform 5.0 API Specification'
-.fl
- \-header '<b>Java 2 Platform </b><br><font size="\-1">5.0</font>'
-.fl
- \-bottom 'Copyright 1993\-2000 Sun Microsystems, Inc. All Rights Reserved.'
+ \-windowtitle 'Java(TM) SE 7 API Specification'
+.fl
+ \-doctitle 'Java(TM) SE 7 API Specification'
+.fl
+ \-header '<b>Java(TM); SE 7'
+.fl
+ \-bottom 'Copyright 1993\-2009 Sun Microsystems, Inc. All Rights Reserved.'
.fl
\-group "Core Packages" "java.*"
.fl
- \-overview /java/pubs/ws/1.5/src/share/classes/overview\-core.html
-.fl
- \-sourcepath /java/pubs/ws/1.5/src/share/classes
+ \-overview /java/pubs/ws/1.7.0/src/share/classes/overview\-core.html
+.fl
+ \-sourcepath /java/pubs/ws/1.7.0/src/share/classes
.fl
\fP
.fi
@@ -4873,25 +5023,38 @@
% \fP\f3javadoc @bottom @packages\fP
.fl
.fi
-.SH NAME
+
+.LP
+
+.LP
+.SH "Name"
Running
+.LP
.SH "RUNNING JAVADOC"
.LP
+
+.LP
.LP
\f3Version Numbers\fP \- The version number of javadoc can be determined using \f3javadoc \-J\-version\fP. The version number of the standard doclet appears in its output stream. It can be turned off with \f2\-quiet\fP.
.LP
.LP
-\f3Public programmatic interface\fP \- To invoke the Javadoc tool from within programs written in the Java language. This interface is in \f2com.sun.tools.javadoc.Main\fP (and javadoc is re\-entrant). For more details, see Standard Doclet.
-.LP
-.LP
-\f3Running Doclets\fP \- The instructions given below are for invoking the standard HTML doclet. To invoke a custom doclet, use the \-doclet and \-docletpath options. For full, working examples of running a particular doclet, see
+\f3Public programmatic interface\fP \- To invoke the Javadoc tool from within programs written in the Java language. This interface is in \f2com.sun.tools.javadoc.Main\fP (and javadoc is re\-entrant). For more details, see
.na
-\f2Running the MIF Doclet\fP @
+\f2Standard Doclet\fP @
.fi
-http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html#runningmifdoclet.
+http://java.sun.com/javase/6/docs/technotes/guides/javadoc/standard\-doclet.html#runningprogrammatically.
+.LP
+.LP
+\f3Running Doclets\fP \- The instructions given below are for invoking the standard HTML doclet. To invoke a custom doclet, use the \-doclet and \-docletpath options. For full, working examples of running a particular doclet, see the
+.na
+\f2MIF Doclet documentation\fP @
+.fi
+http://java.sun.com/j2se/javadoc/mifdoclet/docs/mifdoclet.html.
.LP
.SH "SIMPLE EXAMPLES"
.LP
+
+.LP
.LP
You can run javadoc on entire packages or individual source files. Each package name has a corresponding directory name. In the following examples, the source files are located at \f2/home/src/java/awt/*.java\fP. The destination directory is \f2/home/html\fP.
.LP
@@ -5014,8 +5177,10 @@
.LP
.SH "REAL WORLD EXAMPLE"
.LP
-.LP
-The Javadoc tool has many useful options, some of which are more commonly used than others. Here is effectively the command we use to run the Javadoc tool on the Java platform API. We use 180MB of memory to generate the documentation for the 1500 (approx.) public and protected classes in the Java 2 Platform, Standard Edition, v1.2.
+
+.LP
+.LP
+The Javadoc tool has many useful options, some of which are more commonly used than others. Here is effectively the command we use to run the Javadoc tool on the Java platform API. We use 180MB of memory to generate the documentation for the 1500 (approx.) public and protected classes in the Java SE Platform, Standard Edition, v1.2.
.LP
.LP
The same example is shown twice \-\- first as executed on the command line, then as executed from a makefile. It uses absolute paths in the option arguments, which enables the same \f2javadoc\fP command to be run from any directory.
@@ -5029,21 +5194,21 @@
.nf
\f3
.fl
-% javadoc \-sourcepath /java/jdk/src/share/classes \\
-.fl
- \-overview /java/jdk/src/share/classes/overview.html \\
-.fl
- \-d /java/jdk/build/api \\
-.fl
- \-use \\
-.fl
- \-splitIndex \\
-.fl
- \-windowtitle 'Java 2 Platform 5.0 API Specification' \\
-.fl
- \-doctitle 'Java<sup><font size="\-2">TM</font></sup> 2 Platform 5.0 API Specification' \\
-.fl
- \-header '<b>Java 2 Platform </b><br><font size="\-1">5.0</font>' \\
+% javadoc \-sourcepath /java/jdk/src/share/classes \\
+.fl
+ \-overview /java/jdk/src/share/classes/overview.html \\
+.fl
+ \-d /java/jdk/build/api \\
+.fl
+ \-use \\
+.fl
+ \-splitIndex \\
+.fl
+ \-windowtitle 'Java(TM) Platform, Standard Edition 7 API Specification' \\
+.fl
+ \-doctitle 'Java(TM) Platform, Standard Edition 7 API Specification' \\
+.fl
+ \-header '<b>Java(TM) SE </b><br><font size="\-1">7</font>' \\
.fl
\-bottom '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit
.fl
@@ -5053,9 +5218,9 @@
.fl
901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' \\
.fl
- \-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \\
-.fl
- \-group "Extension Packages" "javax.*" \\
+ \-group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \\
+.fl
+ \-group "Extension Packages" "javax.*" \\
.fl
\-J\-Xmx180m \\
.fl
@@ -5107,17 +5272,17 @@
.fl
java.lang java.lang.reflect \\ /* Sets packages to document */
.fl
- java.util java.io java.net \\
+ java.util java.io java.net \\
.fl
java.applet
.fl
.fl
-WINDOWTITLE = 'Java 2 Platform v1.2 API Specification'
-.fl
-DOCTITLE = 'Java<sup><font size="\-2">TM</font></sup> 2 Platform v1.2 API Specification'
-.fl
-HEADER = '<b>Java 2 Platform </b><br><font size="\-1">v1.2</font>'
+WINDOWTITLE = 'Java(TM) SE 7 API Specification'
+.fl
+DOCTITLE = 'Java(TM) Platform Standard Edition 7 API Specification'
+.fl
+HEADER = '<b>Java(TM) SE 7</font>'
.fl
BOTTOM = '<font size="\-1"><a href="http://java.sun.com/cgi\-bin/bugreport.cgi">Submit
.fl
@@ -5133,7 +5298,7 @@
.fl
GROUPEXT = '"Extension Packages" "javax.*"'
.fl
-SRCDIR = '/java/jdk/1.2/src/share/classes'
+SRCDIR = '/java/jdk/1.7.0/src/share/classes'
.fl
\fP
.fi
@@ -5160,6 +5325,8 @@
.LP
.SH "TROUBLESHOOTING"
.LP
+
+.LP
.SS
General Troubleshooting
.LP
@@ -5173,11 +5340,7 @@
http://java.sun.com/j2se/javadoc/faq/index.html#B
.TP 2
o
-\f3Bugs and Limitations\fP \- You can also see some bugs listed at
-.na
-\f2Important Bug Fixes and Changes\fP @
-.fi
-http://java.sun.com/j2se/1.5.0/fixedbugs/index.html.
+\f3Bugs and Limitations\fP \- You can also see some bugs listed at Important Bug Fixes and Changes.
.TP 2
o
\f3Version number\fP \- See version numbers.
@@ -5202,6 +5365,8 @@
.LP
.SH "ENVIRONMENT"
.LP
+
+.LP
.RS 3
.TP 3
CLASSPATH
@@ -5212,22 +5377,24 @@
.LP
.SH "SEE ALSO"
.LP
+
+.LP
.RS 3
.TP 2
o
-javac
+javac(1)
.TP 2
o
-java
+java(1)
.TP 2
o
-jdb
+jdb(1)
.TP 2
o
-javah
+javah(1)
.TP 2
o
-javap
+javap(1)
.TP 2
o
.na
@@ -5242,12 +5409,22 @@
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
.TP 2
o
-Setting the Class Path
+.na
+\f2Setting the Class Path\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/tools/index.html#general
.TP 2
o
-How Javac and Javadoc Find Classes (tools.jar)
+.na
+\f2How Javac and Javadoc Find Classes\fP @
+.fi
+http://java.sun.com/javase/6/docs/technotes/tools/findingclasses.html#srcfiles (tools.jar)
.RE
.LP
-.LP
-Javadoc is a trademark of Sun Microsystems, Inc. (The \f2javadoc\fP command itself does not require the trademark symbol.)
+
+.LP
+.LP
+Javadoc is a trademark of Sun Microsystems, Inc. (The \f2javadoc\fP command itself does not require the trademark symbol.)
+.LP
+