jdk-sandbox: comparison jdk/src/solaris/doc/sun/man/man1/javadoc.1

equal deleted inserted replaced

-:dc0feb520d54
+:91b22707521a
 '\" t
-.\"  Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved.
+.\" Copyright (c) 1994, 2015, Oracle and/or its affiliates. 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
 .\" under the terms of the GNU General Public License version 2 only, as
 .\" published by the Free Software Foundation.
 .\"
 .\" This code is distributed in the hope that it will be useful, but WITHOUT
 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 .\" version 2 for more details (a copy is included in the LICENSE file that
 .\" accompanied this code).
 .\"
 .\" You should have received a copy of the GNU General Public License version
 .\" 2 along with this work; if not, write to the Free Software Foundation,
 .\" or visit www.oracle.com if you need additional information or have any
 .\" questions.
 .\"
 .\"     Arch: generic
 .\"     Software: JDK 8
-.\"     Date: 10 May 2011
+.\"     Date: 03 March 2015
 .\"     SectDesc: Basic Tools
 .\"     Title: javadoc.1
 .\"
 .if n .pl 99999
-.TH javadoc 1 "10 May 2011" "JDK 8" "Basic Tools"
+.TH javadoc 1 "03 March 2015" "JDK 8" "Basic Tools"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .\" http://bugs.debian.org/507673
 .fi
 .nf
 \f3package java\&.lang\&.applet;\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 The package\&.html File
 .fi
 .nf
 \f3initialize, start, and stop the applet\&. \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3@since 1\&.0 \fP
 .fi
 .nf
 .fi
 .nf
 \f3</HTML>\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The \f3package\&.html\fR 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 \f3/**\fR and \f3*/\fR 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 \f3<body>\fR tag and the first sentence\&. You can include package tags\&. All block tags must appear after the main description\&. If you add an \f3@see\fR tag in a package comment file, then it must have a fully qualified name\&.
 .PP
 Processing the Comment File
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .SS TEST\ AND\ TEMPLATE\ FILES
 You can store test and template files in the source tree in the same directory with or in a subdirectory of the directory where the source files reside\&. To prevent test and template files from being processed, run the \f3javadoc\fR command and explicitly pass in individual source file names\&.
 .PP
 .sp
 .nf
 \f3com/package1/test\-files/\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 If your test files contain documentation comments, then you can set up a separate run of the \f3javadoc\fR command to produce test file documentation by passing in their test source file names with wild cards, such as \f3com/package1/test-files/*\&.java\fR\&.
 .PP
 Template Files
 .fi
 .nf
 \f3implements Serializable\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The declaration for the \f3Boolean\&.valueOf\fR method is:
 .sp
 .nf
 \f3public static Boolean valueOf(String s)\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The \f3javadoc\fR command can include the modifiers \f3public\fR, \f3protected\fR, \f3private\fR, \f3abstract\fR, \f3final\fR, \f3static\fR, \f3transient\fR, and \f3volatile\fR, but not \f3synchronized\fR or \f3native\fR\&. The \f3synchronized\fR and \f3native\fR modifiers are considered implementation detail and not part of the API specification\&.
 .PP
 Rather than relying on the keyword \f3synchronized\fR, APIs should document their concurrency semantics in the main description of the comment\&. For example, a description might be: A single enumeration cannot be used by multiple threads concurrently\&. The document should not describe how to achieve these semantics\&. As another example, while the \f3Hashtable\fR option should be thread-safe, there is no reason to specify that it is achieved by synchronizing all of its exported methods\&. It is better to reserve the right to synchronize internally at the bucket level for higher concurrency\&.
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 To save space you can put a comment on one line:
 .sp
 .nf
 \f3/** This comment takes up only one line\&. */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Placement of Comments
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3import com\&.example;   // MISTAKE \- Important not to put import statement here\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3public class Whatever{ }\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Parts of Comments
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Block and inline Tags
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Write Comments in HTML
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Leading Asterisks
 .fi
 .nf
 \f3public int x, y;      // Avoid this \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The \f3javadoc\fR command generates the following documentation from the previous code:
 .sp
 .nf
 \f3public int x\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The horizontal and vertical distances of point (x, y)\&.
 .sp
 .nf
 \f3public int y\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The horizontal and vertical distances of point (x, y)\&.
 .PP
 Use of Header Tags
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 This tag is needed because the generated documents are in hierarchical directories, as deep as the number of subpackages\&. The expression: \f3<a href="{@docRoot}/copyright\&.html">\fR resolves to \f3<a href="\&.\&./\&.\&./copyright\&.html">\fR for \f3java/lang/Object\&.java\fR and \f3<a href="\&.\&./\&.\&./\&.\&./copyright\&.html">\fR for \f3java/lang/ref/Reference\&.java\fR\&.
 \(bu
 In the main description block of a method\&. In this case, the main description is copied from a class or interface up the hierarchy\&.
 .TP 0.2i
 \(bu
 In the text arguments of the \f3@return\fR, \f3@param,\fR and \f3@throws\fR tags of a method\&. In this case, the tag text is copied from the corresponding tag up the hierarchy\&.
 .RE
-.RS
 See Method Comment Inheritance for a description of how comments are found in the inheritance hierarchy\&. Note that if this tag is missing, then the comment is or is not automatically inherited according to rules described in that section\&.
-.RE
 .TP
 {@link \fIpackage\&.class#member label\fR}
 Introduced in JDK 1\&.2
 Inserts an inline link with a 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 documentation comments: overview, package, class, interface, constructor, method and field, including the text portion of any tag, such as the \f3@return\fR, \f3@param\fR and \f3@deprecated\fR tags\&. See @link in How to Write Doc Comments for the Javadoc Tool at http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#{@link
 .sp
 .nf
 \f3Use the {@link #getComponentAt(int, int) getComponentAt} method\&.\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 From this code, the standard doclet generates the following HTML (assuming it refers to another class in the same package):
 .sp
 .nf
 \f3Use the <a href="Component\&.html#getComponentAt(int, int)">getComponentAt</a> method\&.\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The previous line appears on the web page as:
 .sp
 .nf
 \f3Use the getComponentAt method\&.\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 {@linkplain \fIpackage\&.class#member label\fR}
 .fi
 .nf
 \f3}\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 Example of a type parameter of a method:
 .fi
 .nf
 \f3}\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 @return \fIdescription\fR
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The standard doclet produces HTML that is similar to:
 .fi
 .nf
 \f3</dl>\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The previous code looks similar to the following in a browser, where the label is the visible link text:
 .fi
 .nf
 \f3@see #constructor(Type argname, Type argname,\&.\&.\&.) \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3\fIReferencing another class in the current or imported packages\fR\fP
 .fi
 .nf
 .fi
 .nf
 \f3@see Class \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3\fIReferencing an element in another package (fully qualified)\fR\fP
 .fi
 .nf
 .fi
 .nf
 \f3@see package\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3\fRNotes about the previous listing:
 .TP 0.2i
 \(bu
 .TP 0.4i
 2\&.
 Any enclosing classes and interfaces searching the closest first\&.
 .TP 0.4i
 3\&.
-Any superclasses and superonterfaces, searching the closest first\&.
+Any superclasses and superinterfaces, searching the closest first\&.
 .TP 0.4i
 4\&.
 The current package\&.
 .TP 0.4i
 5\&.
 .fi
 .nf
 \f3@see "The Java Programming Language"    //  "The Java Programming Language" \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \fINote:\fR You can extend the \f3@se\fR\f3e\fR tag to link to classes not being documented with the \f3-link\fR option\&.
 .TP
 @serial \fIfield-description\fR | include | exclude
 Introduced in JDK 1\&.2
 Used in the documentation comment for a default serializable field\&. See Documenting Serializable Fields and Data for a Class at http://docs\&.oracle\&.com/javase/8/docs/platform/serialization/spec/serial-arch\&.html#5251
-See also Oracle\(cqs Criteria for Including Classes in the Serialilzed Form Specification at http://www\&.oracle\&.com/technetwork/java/javase/documentation/serialized-criteria-137781\&.html
+See also Oracle\(cqs Criteria for Including Classes in the Serialized Form Specification at http://www\&.oracle\&.com/technetwork/java/javase/documentation/serialized-criteria-137781\&.html
 An optional \f3field-description\fR should explain the meaning of the field and list the acceptable values\&. When needed, the description can span multiple lines\&. The standard doclet adds this information to the serialized form page\&. See Cross-Reference Pages\&.
 If a serializable field was added to a class after the class was made serializable, then a statement should be added to its main description to identify at which version it was added\&.
 \(bu
 A public or protected class that implements \f3Serializable\fR is included unless that class (or its package) is marked with the \f3@serial exclude\fR tag\&.
 .TP 0.2i
 \(bu
 A private or package-private class that implements \f3Serializable\fR is excluded unless that class (or its package) is marked with the \f3@serial include\fR tag\&.
 .RE
-.RS
 For example, the \f3javax\&.swing\fR package is marked with the \f3@serial\fR\f3exclude\fR tag in package\&.html or package-info\&.java\&. The public class \f3java\&.security\&.BasicPermission\fR is marked with the \f3@serial exclude\fR tag\&. The package-private class \f3java\&.util\&.PropertyPermissionCollection\fR is marked with the \f3@serial include\fR tag\&.
 The \f3@serial\fR tag at the class level overrides the \f3@serial\fR tag at the package level\&.
-.RE
 .TP
 @serialData \fIdata-description\fR
 Introduced in JDK 1\&.2
 Uses the data description value to document the types and order of data in the serialized form\&. This data includes the optional data written by the \f3writeObject\fR method and all data (including base classes) written by the \f3Externalizable\&.writeExternal\fR method\&.
 .fi
 .nf
 \f3public static final String SCRIPT_START = "<script>"\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 When used with the argument \f3package\&.class#field\fR in any documentation comment, he \f3{@value}\fR tag displays the value of the specified constant:
 .fi
 .nf
 \f3public String evalScript(String script) {}\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The argument \f3package\&.class#field\fR takes a form similar to that of the \f3@see\fR tag argument, except that the member must be a static field\&.
 .fi
 .nf
 \f3}\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .SS FIELD\ TAGS
 These tags can appear in fields:
 .PP
 .fi
 .nf
 \f3    int x = 1263732;\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .SS CONSTRUCTOR\ AND\ METHOD\ TAGS
 The following tags can appear in the documentation comment for a constructor or a method, except for the \f3@return\fR tag, which cannot appear in a constructor, and the \f3{@inheritDoc}\fR tag, which has restrictions\&.
 .PP
 .fi
 .nf
 \f3    }\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .SH OPTIONS
 The \f3javadoc\fR command uses doclets to determine its output\&. The \f3javadoc\fR command uses the default standard doclet unless a custom doclet is specified with the \f3-doclet\fR option\&. The \f3javadoc\fR command provides a set of command-line options that can be used with any doclet\&. These options are described in Javadoc Options\&. The standard doclet provides an additional set of command-line options that are described in Standard Doclet Options\&. All option names are not case-sensitive, but their arguments are case-sensitive\&.
 .TP 0.2i
 \(bu
 See also Standard Doclet Options
 .PP
 The options are:
 .PP
--1\&.1 || -author || -bootclasspath classpathlist || -bottom text || -breakiterator || -charset name || -classpath classpathlist || -d directory || -docencoding name || -docfilesubdirs || -doclet class || -docletpath classpathlist || -doctitle title || -encoding || -exclude packagename1:packagename2:\&.\&.\&. || -excludedocfilessubdir name1:name2 || -extdirs dirist || -footer footer || -group groupheading packagepattern:packagepattern || -header header || -help || -helpfile path\efilename || -Jflag || -keywords || -link extdocURL || -linkoffline extdocURL packagelistLoc || -linksource || -locale language_country_variant || -nocomment || -nodeprecated || -nodeprecatedlist || -nohelp || -noindex || -nonavbar || -noqualifier all | packagename1:packagename2\&.\&.\&. || -nosince || -notimestamp || -notree || -overview path/filename || -package || -private || -protected || -public || -quiet || -serialwarn || -source release || -sourcepath sourcepathlist || -sourcetab tablength || -splitindex || -stylesheet path/filename || -subpackages package1:package2:\&.\&.\&. || -tag tagname:Xaoptcmf:"taghead" || -taglet class || -tagletpath tagletpathlist || -title title || -top || -use || -verbose || -version || -windowtitle title
+-1\&.1 || -author || -bootclasspath classpathlist || -bottom text || -breakiterator || -charset name || -classpath classpathlist || -d directory || -docencoding name || -docfilesubdirs || -doclet class || -docletpath classpathlist || -doctitle title || -encoding || -exclude packagename1:packagename2:\&.\&.\&. || -excludedocfilessubdir name1:name2 || -extdirs dirist || -footer footer || -group groupheading packagepattern:packagepattern || -header header || -help || -helpfile path\efilename || -Jflag || -javafx ||-keywords || -link extdocURL || -linkoffline extdocURL packagelistLoc || -linksource || -locale language_country_variant || -nocomment || -nodeprecated || -nodeprecatedlist || -nohelp || -noindex || -nonavbar || -noqualifier all | packagename1:packagename2\&.\&.\&. || -nosince || -notimestamp || -notree || -overview path/filename || -package || -private || -protected || -public || -quiet || -serialwarn || -source release || -sourcepath sourcepathlist || -sourcetab tablength || -splitindex || -stylesheet path/filename || -subpackages package1:package2:\&.\&.\&. || -tag tagname:Xaoptcmf:"taghead" || -taglet class || -tagletpath tagletpathlist || -title title || -top || -use || -verbose || -version || -windowtitle title
 .PP
 The following options are the core Javadoc options that are available to all doclets\&. The standard doclet provides the rest of the doclets: \f3-bootclasspath\fR, \f3-breakiterator\fR, \f3-classpath\fR, \f3-doclet\fR, \f3-docletpath\fR, \f3-encoding\fR, -\f3exclude\fR, \f3-extdirs\fR, \f3-help\fR, \f3-locale\fR, \f3-\fR\f3overview\fR, \f3-package\fR, \f3-private\fR, \f3-protected\fR, \f3-public\fR, \f3-quiet\fR, \f3-source\fR, \f3-sourcepath\fR, \f3-subpackages\fR, and \f3-verbose\fR\&.
 .SS JAVADOC\ OPTIONS
 .TP
 -overview \fIpath/filename\fR
 \(bu
 \f3-Xdoclint all\fR : enable all groups of checks
 .TP 0.2i
 \(bu
 \f3-Xdoclint all,\fR\fI-group\fR : enable all except \fIgroup\fR checks
 .RE
-.RS
 The variable \fIgroup\fR has one of the following values:
 .RS
-.RE
 .TP 0.2i
 \(bu
 \f3accessibility\fR : Checks for the issues to be detected by an accessibility checker (for example, no caption or summary attributes specified in a \f3<table>\fR tag)\&.
 .TP 0.2i
 \(bu
 \(bu
 \f3reference\fR : Checks for issues relating to the references to Java API elements from Javadoc tags (for example, item not found in \f3@see\fR , or a bad name after \f3@param)\fR\&.
 .TP 0.2i
 \(bu
 \f3syntax\fR : Checks for low level issues like unescaped angle brackets (\f3<\fR and \f3>\fR) and ampersands (\f3&\fR) and invalid Javadoc tags\&.
 .RE
-.RS
 You can specify the \f3-Xdoclint\fR option multiple times to enable the option to check errors and warnings in multiple categories\&. Alternatively, you can specify multiple error and warning categories by using the preceding options\&. For example, use either of the following commands to check for the HTML, syntax, and accessibility issues in the file \fIfilename\fR\&.
 .sp
 .nf
 \f3javadoc \-Xdoclint:html \-Xdoclint:syntax \-Xdoclint:accessibility \fIfilename\fR\fP
 .fi
 .nf
 \f3javadoc \-Xdoclint:html,syntax,accessibility \fIfilename\fR\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \fINote:\fR The \f3javadoc\fR command does not guarantee the completeness of these checks\&. In particular, it is not a full HTML compliance checker\&. The goal of the -\f3Xdoclint\fR option is to enable the \f3javadoc\fR command to report majority of common errors\&.
 The \f3javadoc\fR command does not attempt to fix invalid input, it just reports it\&.
-.RE
 .TP
 -public
 .br
 Shows only public classes and members\&.
 .TP
 .sp
 .nf
 \f3javadoc \-sourcepath /home/user/src/ com\&.mypackage\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 Notice that if you concatenate the value of sourcepath and the package name together and change the dot to a slash (/), then you have the full path to the package:
 .sp
 .nf
 \f3javadoc \-sourcepath /home/user1/src:/home/user2/src com\&.mypackage\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -classpath \fIclasspathlist\fR
 .br
 Specifies the paths where the \f3javadoc\fR command searches for referenced classes These are the documented classes plus any classes referenced by those classes\&. Separate multiple paths with a colon (:)\&. The \f3javadoc\fR command searches all subdirectories of the specified paths\&. Follow the instructions in the class path documentation for specifying the \f3classpathlist\fR value\&.
 If you omit \f3-sourcepath\fR, then the \f3javadoc\fR command uses \f3-classpath\fR to find the source files and class files (for backward compatibility)\&. If you want to search for source and class files in separate paths, then use both \f3-sourcepath\fR and \f3-classpath\fR\&.
-For example, if you want to document \f3com\&.mypackage\fR, whose source files reside in the directory /home/user/src/com/mypackage, and if this package relies on a library in /home/user/libthen you would use the following command:
+For example, if you want to document \f3com\&.mypackage\fR, whose source files reside in the directory /home/user/src/com/mypackage, and if this package relies on a library in /home/user/lib, then you would use the following command:
 .sp
 .nf
 \f3javadoc \-sourcepath /home/user/lib \-classpath /home/user/src com\&.mypackage\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 Similar to other tools, if you do not specify \f3-classpath\fR, then the \f3javadoc\fR command uses the \f3CLASSPATH\fR environment variable when it is set\&. If both are not set, then the \f3javadoc\fR command searches for classes from the current directory\&.
 .sp
 .nf
 \f3javadoc \-d docs \-sourcepath /home/user/src  \-subpackages java:javax\&.swing \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -exclude \fIpackagename1:packagename2:\&.\&.\&.\fR
 .fi
 .nf
 \f3    java\&.net:java\&.lang\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -bootclasspath \fIclasspathlist\fR
 \(bu
 English default sentence-break algorithm\&. Stops at a period followed by a space or an HTML block tag, such as \f3<P>\fR\&.
 .TP 0.2i
 \(bu
 Breakiterator sentence-break algorithm\&. Stops at a period, question mark, or exclamation point followed by a space when the next word starts with a capital letter\&. This is meant to handle most abbreviations (such as "The serial no\&. is valid", but will not handle "Mr\&. Smith")\&. The \f3-breakiterator\fR option does not stop at HTML tags or sentences that begin with numbers or symbols\&. The algorithm stops at the last period in \&.\&./filename, even when embedded in an HTML tag\&.
 .RE
-.RS
 In Java SE 1\&.5 the \f3-breakiterator\fR option warning messages are removed, and the default sentence-break algorithm is unchanged\&. If you have not modified your source code to eliminate the \f3-breakiterator\fR option warnings in Java SE 1\&.4\&.x, then you do not have to do anything\&. The warnings go away starting with Java SE 1\&.5\&.0\&.
-.RE
 .TP
 -locale \fIlanguage_country_variant\fR
 .br
 Specifies the locale that the \f3javadoc\fR command uses when it generates documentation\&. The argument is the name of the locale, as described in \f3j\fR\f3ava\&.util\&.Locale\fR documentation, such as \f3en_US\fR (English, United States) or \f3en_US_WIN\fR (Windows variant)\&.
 .fi
 .nf
 \f3Java HotSpot(TM) 64\-Bit Server VM (build 23\&.5\-b02, mixed mode)\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
+.fi
+.sp
+.TP
+-javafx
+.br
+Generates HTML documentation using the JavaFX extensions to the standard doclet\&. The generated documentation includes a Property Summary section in addition to the other summary sections generated by the standard Java doclet\&. The listed properties are linked to the sections for the getter and setter methods of each property\&.
+If there are no documentation comments written explicitly for getter and setter methods, the documentation comments from the property method are automatically copied to the generated documentation for these methods\&. This option also adds a new \f3@defaultValue\fR tag that allows documenting the default value for a property\&.
+Example:
+.sp
+.nf
+\f3javadoc \-javafx MyClass\&.java \-d testdir\fP
 .fi
 .sp
 .SS STANDARD\ DOCLET\ OPTIONS
 .TP
 .fi
 .nf
 \f3\-link <directory>/<directory>/\&.\&.\&./<name>\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Differences between the -linkoffline and -link options
 .sp
 .nf
 \f3javadoc \-link http://docs\&.oracle\&.com/javase/8/docs/api/ com\&.mypackage\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The command generates documentation for the package \f3com\&.mypackage\fR with links to the Java SE packages\&. The generated documentation contains links to the \f3Object\fR class, for example, in the class \f3trees\fR\&. Other options, such as the \f3-sourcepath\fR and \f3-d\fR options, are not shown\&.
 .PP
 \f3Example 2 Relative Link to External Documents\fR
 .fi
 .nf
 \f3and so on \&.\&.\&.\&.\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 When \f3javadoc\fR is run without the \f3-link\fR option and encounters a name that belongs to an externally referenced class, it prints the name with no link\&. However, when the \f3-link\fR option is used, the \f3javadoc\fR command searches the package-list file at the specified \fIextdocURL\fR location for that package name\&. When it finds the package name, it prefixes the name with \fIextdocURL\fR\&.
 .PP
 For there to be no broken links, all of the documentation for the external references must exist at the specified URLs\&. The \f3javadoc\fR command does not check that these pages exist, but only that the package-list exists\&.
 .sp
 .nf
 \f3javadoc \-linkoffline http://docs\&.oracle\&.com/javase/8/docs/api/ \&.  com\&.mypackage \fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Relative Links to External Documents
 .fi
 .nf
 \f3packagelistLoc2 \&.\&.\&.\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Update Documents
 .sp
 .nf
 \f3javadoc \-d update \-linkoffline \&. html com\&.mypackage\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 When the \f3javadoc\fR command completes, copy these generated class pages in update/com/package (not the overview or index) to the original files in html/com/package\&.
 .TP
 -linksource
 .sp
 .nf
 \f3public class Button extends Component implements Accessible\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The link to the source code of the \f3getLabel\fR method in the \f3Button\fR class is on the word \f3getLabel\fR:
 .sp
 .nf
 \f3public String getLabel()\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -group groupheading \fIpackagepattern:packagepattern\fR
 \(bu
 The \f3groupheading\fR can be any text and can include white space\&. This text is placed in the table heading for the group\&.
 .TP 0.2i
 \(bu
 The \f3packagepattern\fR value can be any package name at the start of any package name followed by an asterisk (*)\&. The asterisk is the only wildcard allowed and means match any characters\&. Multiple patterns can be included in a group by separating them with colons (:)\&. If you use an asterisk in a pattern or pattern list, then the pattern list must be inside quotation marks, such as \f3"java\&.lang*:java\&.util"\fR\&.
 .RE
-.RS
 When you do not supply a \f3-group\fR option, all packages are placed in one group with the heading \fIPackages\fR and appropriate subheadings\&. If the subheadings do not include all documented packages (all groups), then the remaining packages appear in a separate group with the subheading Other Packages\&.
 For example, the following \f3javadoc\fR command separates the three documented packages into \fICore\fR, \fIExtension\fR, and \fIOther Packages\fR\&. The trailing dot (\&.) does not appear in \f3java\&.lang*\fR\&. Including the dot, such as \f3java\&.lang\&.*\fR omits the\f3java\&.lang\fR package\&.
 .sp
 .nf
 .fi
 .nf
 \f3        java\&.lang java\&.lang\&.reflect java\&.util javax\&.servlet java\&.new\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \fICore Packages\fR
 \f3javax\&.servlet\fR
 \fIOther Packages\fR
 \f3java\&.new\fR
-.RE
 .TP
 -nodeprecated
 .br
 Prevents the generation of any deprecated API in the documentation\&. This does what the \f3-nodeprecatedlist\fR option does, and it does not generate any deprecated API throughout the rest of the documentation\&. This is useful when writing code when you do not want to be distracted by the deprecated code\&.
 .TP
 .sp
 .nf
 \f3javadoc \-helpfile /home/user/myhelp\&.html java\&.awt\&.\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -stylesheet \fIpath/filename\fR
 .sp
 .nf
 \f3javadoc \-stylesheet file /home/user/mystylesheet\&.css com\&.mypackage\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -serialwarn
 .sp
 .nf
 \f3<META http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1">\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 This \f3META\fR tag is described in the HTML standard (4197265 and 4137321), HTML Document Representation, at http://www\&.w3\&.org/TR/REC-html40/charset\&.html#h-5\&.2\&.2
 .TP
 -docencoding \fIname\fR
 .br
 Specifies the encoding of the generated HTML files\&. The name should be a preferred MIME name as specified in the IANA Registry, Character Sets at http://www\&.iana\&.org/assignments/character-sets
-If you omit the \f3-docencoding\fR option but use the \f3-encoding\fR option, then the encoding of the generated HTML files is determined by the \f3-encoding\fR option, for example: \f3javadoc -docencoding"iso-8859-1" mypackage\fR\&. See also the \f3-encoding\fR and \f3-docencoding name\fR options\&.
+If you omit the \f3-docencoding\fR option but use the \f3-encoding\fR option, then the encoding of the generated HTML files is determined by the \f3-encoding\fR option, for example: \f3javadoc -docencoding "iso-8859-1" mypackage\fR\&. See also the \f3-encoding\fR and \f3-docencoding name\fR options\&.
 .TP
 -keywords
 .br
 Adds HTML keyword <META> tags to the generated file for each class\&. These tags can help search engines that look for <META> tags find the pages\&. Most search engines that search the entire Internet do not look at <META> tags, because pages can misuse them\&. Search engines offered by companies that confine their searches to their own website can benefit by looking at <META> tags\&. The <META> tags include the fully qualified name of the class and the unqualified names of the fields and methods\&. Constructors are not included because they are identical to the class name\&. For example, the class \f3String\fR starts with these keywords:
 .sp
 .fi
 .nf
 \f3<META NAME="keywords" CONTENT="charAt()">\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -tag \fItagname\fR:Xaoptcmf:"\fItaghead\fR"
 .fi
 .nf
 \f3 */\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \fISpell-checking tag names\fR: Some developers put custom tags in the source code that they do not always want to output\&. In these cases, it is important to list all tags that are in the source code, enabling the ones you want to output and disabling the ones you do not want to output\&. The presence of \f3X\fR disables the tag, while its absence enables the tag\&. This gives the \f3javadoc\fR command enough information to know whether a tag it encounters is unknown, which is probably the results of a typographical error or a misspelling\&. The \f3javadoc\fR command prints a warning in these cases\&. You can add \f3X\fR to the placement values already present, so that when you want to enable the tag, you can simply delete the \f3X\fR\&. For example, if the \f3@todo\fR tag is a tag that you want to suppress on output, then you would use: \f3-tag todo:Xcmf:"To Do:"\fR\&. If you would rather keep it simple, then use this: \f3-tag todo:X\fR\&. The syntax \f3-tag todo:X\fR works even when the \f3@todo\fR tag is defined by a taglet\&.
 .fi
 .nf
 \f3\-tag example:X\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 When the \f3javadoc\fR command parses the documentation comments, any tag encountered that is neither a standard tag nor passed in with the \f3-tag\fR or \f3-taglet\fR options is considered unknown, and a warning is thrown\&.
 .fi
 .nf
 \f3\-tag see\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .TP
 -tagletpath \fItagletpathlist\fR
 .fi
 .nf
 \f3\-sourcepath /java/pubs/ws/1\&.7\&.0/src/share/classes\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 Create a file named packages that contains:
 .sp
 .nf
 .fi
 .nf
 \f3com\&.mypackage3\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 Run the \f3javadoc\fR command as follows:
 .sp
 .nf
 \f3javadoc @options @packages\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3Example 3 Argument Files with Paths\fR
 .PP
 The argument files can have paths, but any file names inside the files are relative to the current working directory (not \f3path1\fR or \f3path2\fR):
 .sp
 .nf
 \f3javadoc @path1/options @path2/packages\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3Example 4 Option Arguments\fR
 .PP
 The following example saves an argument to a \f3javadoc\fR command option in an argument file\&. The \f3-bottom\fR option is used because it can have a lengthy argument\&. You could create a file named bottom to contain the text argument:
 .fi
 .nf
 \f3    Other names may be trademarks of their respective owners\&.</font>\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 Run the \f3javadoc\fR command as follows:\f3javadoc -bottom @bottom @packages\fR\&.
 .PP
 You can also include the \f3-bottom\fR option at the start of the argument file and run the \f3javadoc\fR command as follows: \f3javadoc @bottom @packages\fR\&.
 .sp
 .nf
 \f3javadoc \-d /home/html \-sourcepath /home/src \-subpackages java \-exclude\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3Example 2 Change to Root and Run Explicit Packages\fR
 .PP
 Change to the parent directory of the fully qualified package\&. Then, run the \f3javadoc\fR command with the names of one or more packages that you want to document:
 .fi
 .nf
 \f3javadoc \-d /home/html java\&.awt java\&.awt\&.event\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 To also traverse down other package trees, append their names to the \f3-subpackages\fR argument, such as j\f3ava:javax:org\&.xml\&.sax\fR\&.
 .PP
 \f3Example 3 Run from Any Directory on Explicit Packages in One Tree\fR
 .sp
 .nf
 \f3javadoc \-d /home/html \-sourcepath /home/src java\&.awt java\&.awt\&.event\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3Example 4 Run from Any Directory on Explicit Packages in Multiple Trees\fR
 .PP
 Run the \f3javadoc\fR command and use the \f3-sourcepath\fR option with a colon-separated list of the paths to each tree\&'s root\&. Provide the names of one or more packages that you want to document\&. All source files for a specified package do not need to be located under a single root directory, but they must be found somewhere along the source path\&.
 .sp
 .nf
 \f3javadoc \-d /home/html \-sourcepath /home/src1:/home/src2 java\&.awt java\&.awt\&.event\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The result is that all cases generate HTML-formatted documentation for the \f3public\fR and \f3protected\fR classes and interfaces in packages j\f3ava\&.awt\fR and \f3java\&.awt\&.even\fRt and save the HTML files in the specified destination directory\&. Because two or more packages are being generated, the document has three HTML frames: one for the list of packages, another for the list of classes, and the third for the main class pages\&.
 .PP
 Document One or More Classes
 .fi
 .nf
 \f3javadoc \-d /home/html Button\&.java Canvas\&.java Graphics*\&.java\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3Example 2 Change to the Root Directory of the Package\fR
 .PP
 This is useful for documenting individual source files from different subpackages off of the same root\&. Change to the package root directory, and supply the source files with paths from the root\&.
 .fi
 .nf
 \f3javadoc \-d /home/html java/awt/Button\&.java java/applet/Applet\&.java\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 \f3Example 3 Document Files from Any Directory\fR
 .PP
 In this case, it does not matter what the current directory is\&. Run the \f3javadoc\fR command with the absolute path (or path relative to the current directory) to the source files you want to document\&.
 .fi
 .nf
 \f3/home/src/java/awt/Graphics*\&.java\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Document Packages and Classes
 .fi
 .nf
 \f3/home/src/java/applet/Applet\&.java\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .SS REAL-WORLD\ EXAMPLES
 The following command-line and \f3makefile\fR versions of the \f3javadoc\fR command run on the Java platform APIs\&. It uses 180 MB of memory to generate the documentation for the 1500 (approximately) public and protected classes in the Java SE 1\&.2\&. Both examples use absolute paths in the option arguments, so that the same \f3javadoc\fR command can be run from any directory\&.
 .PP
 .fi
 .nf
 \f3@packages\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .PP
 Programmatic Interface
 .fi
 .nf
 \f3import javax\&.tools\&.ToolProvider;\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3public class JavaAccessSample{\fP
 .fi
 .nf
 .fi
 .nf
 \f3 }\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 The first three arguments of the \f3run\fR method specify input, standard output, and standard error streams\&. \f3Null\fR is the default value for \f3System\&.in\fR, \f3System\&.out\fR, and \f3System\&.err\fR, respectively\&.
 .SS THE\ MAKEFILE\ EXAMPLE
 This is an example of a GNU \f3makefile\fR\&. Single quotation marks surround \f3makefile\fR arguments\&. For an example of a Windows \f3makefile\fR, see the \f3makefiles\fR section of the Javadoc FAQ at http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137483\&.html#makefiles
 .fi
 .nf
 \f3        java\&.applet\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .nf
 \f3WINDOWTITLE = \&'Java\(tm SE 7 API Specification\&'\fP
 .fi
 .nf
 .fi
 .nf
 \f3SRCDIR = \&'/java/jdk/1\&.7\&.0/src/share/classes\&'\fP
 .fi
 .nf
-\f3\fR
+\f3\fP
 .fi
 .sp
 .SS NOTES
 .TP 0.2i
 \(bu

changeset 31876	91b22707521a
parent 21743	3d979da7bdf0