diff --git a/src/java.base/share/man/keytool.1 b/src/java.base/share/man/keytool.1 index 8a93ac50c0d..a61095d4504 100644 --- a/src/java.base/share/man/keytool.1 +++ b/src/java.base/share/man/keytool.1 @@ -36,7 +36,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "KEYTOOL" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "KEYTOOL" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP @@ -452,17 +452,32 @@ The certificate chain and private key are stored in a new keystore entry that is identified by its alias. .PP The \f[V]-keyalg\f[R] value specifies the algorithm to be used to -generate the key pair, and the \f[V]-keysize\f[R] value specifies the -size of each key to be generated. -The \f[V]-sigalg\f[R] value specifies the algorithm that should be used -to sign the certificate. -This algorithm must be compatible with the \f[V]-keyalg\f[R] value. -.PP +generate the key pair. +The \f[V]-keysize\f[R] value specifies the size of each key to be +generated. The \f[V]-groupname\f[R] value specifies the named group (for example, the standard or predefined name of an Elliptic Curve) of the key to be generated. +.PP +When a \f[V]-keysize\f[R] value is provided, it will be used to +initialize a \f[V]KeyPairGenerator\f[R] object using the +\f[V]initialize(int keysize)\f[R] method. +When a \f[V]-groupname\f[R] value is provided, it will be used to +initialize a \f[V]KeyPairGenerator\f[R] object using the +\f[V]initialize(AlgorithmParameterSpec params)\f[R] method where +\f[V]params\f[R] is \f[V]new NamedParameterSpec(groupname)\f[R]. +.PP Only one of \f[V]-groupname\f[R] and \f[V]-keysize\f[R] can be specified. +If an algorithm has multiple named groups that have the same key size, +the \f[V]-groupname\f[R] option should usually be used. +In this case, if \f[V]-keysize\f[R] is specified, it\[aq]s up to the +security provider to determine which named group is chosen when +generating a key pair. +.PP +The \f[V]-sigalg\f[R] value specifies the algorithm that should be used +to sign the certificate. +This algorithm must be compatible with the \f[V]-keyalg\f[R] value. .PP The \f[V]-signer\f[R] value specifies the alias of a \f[V]PrivateKeyEntry\f[R] for the signer that already exists in the @@ -1570,10 +1585,13 @@ The following examples show the defaults for various option values: 2048 (when using -genkeypair and -keyalg is \[dq]DSA\[dq]) 3072 (when using -genkeypair and -keyalg is \[dq]RSA\[dq], \[dq]RSASSA-PSS\[dq], or \[dq]DH\[dq]) 384 (when using -genkeypair and -keyalg is \[dq]EC\[dq]) - 255 (when using -genkeypair and -keyalg is \[dq]EdDSA\[dq], or \[dq]XDH) 56 (when using -genseckey and -keyalg is \[dq]DES\[dq]) 168 (when using -genseckey and -keyalg is \[dq]DESede\[dq]) +-groupname + ed25519 (when using -genkeypair and -keyalg is \[dq]EdDSA\[dq], key size is 255) + x25519 (when using -genkeypair and -keyalg is \[dq]XDH\[dq], key size is 255) + -validity 90 -keystore <the file named .keystore in the user\[aq]s home directory> @@ -1604,7 +1622,7 @@ l l l. T{ keyalg T}@T{ -keysize +key size T}@T{ default sigalg T} @@ -1621,7 +1639,7 @@ RSA T}@T{ < 624 T}@T{ -SHA256withRSA (keysize is too small for using SHA-384) +SHA256withRSA (key size is too small for using SHA-384) T} T{ T}@T{ @@ -1653,7 +1671,7 @@ RSASSA-PSS T}@T{ < 624 T}@T{ -RSASSA-PSS (with SHA-256, keysize is too small for +RSASSA-PSS (with SHA-256, key size is too small for T} T{ T}@T{ @@ -1701,28 +1719,29 @@ Ed448 T} .TE .IP \[bu] 2 +The key size, measured in bits, corresponds to the size of the private +key. +This size is determined by the value of the \f[V]-keysize\f[R] or +\f[V]-groupname\f[R] options or the value derived from a default +setting. +.IP \[bu] 2 An RSASSA-PSS signature algorithm uses a \f[V]MessageDigest\f[R] algorithm as its hash and MGF1 algorithms. .IP \[bu] 2 -EdDSA supports 2 key sizes: Ed25519 and Ed448. -When generating an EdDSA key pair using \f[V]-keyalg EdDSA\f[R], a user -can specify \f[V]-keysize 255\f[R] or \f[V]-keysize 448\f[R] to generate -Ed25519 or Ed448 key pairs. -When no \f[V]-keysize\f[R] is specified, an Ed25519 key pair is -generated. -A user can also directly specify \f[V]-keyalg Ed25519\f[R] or -\f[V]-keyalg Ed448\f[R] to generate a key pair with the expected key -size. +If neither a default \f[V]-keysize\f[R] or \f[V]-groupname\f[R] is +defined for an algorithm, the security provider will choose a default +setting. .PP \f[B]Note:\f[R] .PP -To improve out of the box security, default key size and signature -algorithm names are periodically updated to stronger values with each -release of the JDK. +To improve out of the box security, default keysize, groupname, and +signature algorithm names are periodically updated to stronger values +with each release of the JDK. If interoperability with older releases of the JDK is important, make sure that the defaults are supported by those releases. -Alternatively, you can use the \f[V]-keysize\f[R] or \f[V]-sigalg\f[R] -options to override the default values at your own risk. +Alternatively, you can use the \f[V]-keysize\f[R], \f[V]-groupname\f[R], +or \f[V]-sigalg\f[R] options to override the default values at your own +risk. .SH SUPPORTED NAMED EXTENSIONS .PP The \f[V]keytool\f[R] command supports these named extensions. diff --git a/src/java.rmi/share/man/rmiregistry.1 b/src/java.rmi/share/man/rmiregistry.1 index 499a5885dd9..29a2e2c965a 100644 --- a/src/java.rmi/share/man/rmiregistry.1 +++ b/src/java.rmi/share/man/rmiregistry.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "RMIREGISTRY" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "RMIREGISTRY" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/java.scripting/share/man/jrunscript.1 b/src/java.scripting/share/man/jrunscript.1 index 9e980755b0f..43029582b3e 100644 --- a/src/java.scripting/share/man/jrunscript.1 +++ b/src/java.scripting/share/man/jrunscript.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JRUNSCRIPT" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JRUNSCRIPT" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.compiler/share/man/javac.1 b/src/jdk.compiler/share/man/javac.1 index b8a7fe60af5..ab429ab7d9a 100644 --- a/src/jdk.compiler/share/man/javac.1 +++ b/src/jdk.compiler/share/man/javac.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JAVAC" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JAVAC" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.compiler/share/man/serialver.1 b/src/jdk.compiler/share/man/serialver.1 index 57148e5f643..cd437b7e9bf 100644 --- a/src/jdk.compiler/share/man/serialver.1 +++ b/src/jdk.compiler/share/man/serialver.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "SERIALVER" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "SERIALVER" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.hotspot.agent/share/man/jhsdb.1 b/src/jdk.hotspot.agent/share/man/jhsdb.1 index 95d5fca297e..30b2d3fe95c 100644 --- a/src/jdk.hotspot.agent/share/man/jhsdb.1 +++ b/src/jdk.hotspot.agent/share/man/jhsdb.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JHSDB" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JHSDB" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.httpserver/share/man/jwebserver.1 b/src/jdk.httpserver/share/man/jwebserver.1 index b8d4e9f8417..3c48d81fc9c 100644 --- a/src/jdk.httpserver/share/man/jwebserver.1 +++ b/src/jdk.httpserver/share/man/jwebserver.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JWEBSERVER" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JWEBSERVER" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jartool/share/man/jar.1 b/src/jdk.jartool/share/man/jar.1 index a1a7f14a55a..26d2c422b2d 100644 --- a/src/jdk.jartool/share/man/jar.1 +++ b/src/jdk.jartool/share/man/jar.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JAR" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JAR" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jartool/share/man/jarsigner.1 b/src/jdk.jartool/share/man/jarsigner.1 index 2f442ff70ca..ea8f686a4c8 100644 --- a/src/jdk.jartool/share/man/jarsigner.1 +++ b/src/jdk.jartool/share/man/jarsigner.1 @@ -36,7 +36,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JARSIGNER" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JARSIGNER" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP @@ -318,7 +318,7 @@ l l l l. T{ keyalg T}@T{ -keysize +key size T}@T{ default sigalg T}@T{ @@ -420,6 +420,9 @@ Otherwise, jarsigner will use parameters that are determined by the size of the key as specified in the table above. For example, an 3072-bit RSASSA-PSS key will use RSASSA-PSS as the signature algorithm and SHA-384 as the hash and MGF1 algorithms. +.IP \[bu] 2 +If a key algorithm is not listed in this table, the \f[V].DSA\f[R] +extension is used when signing a JAR file. .PP These default signature algorithms can be overridden by using the \f[V]-sigalg\f[R] option. @@ -805,8 +808,8 @@ Specifies the name of the message digest algorithm to use when digesting the entries of a JAR file. .RS .PP -For a list of standard message digest algorithm names, see Java Security -Standard Algorithm Names. +For a list of standard message digest algorithm names, see the Java +Security Standard Algorithm Names Specification. .PP If this option isn\[aq]t specified, then \f[V]SHA-384\f[R] is used. There must either be a statically installed provider supplying an @@ -830,8 +833,8 @@ implementation of the specified algorithm or you must specify one with the \f[V]-addprovider\f[R] or \f[V]-providerClass\f[R] option; otherwise, the command doesn\[aq]t succeed. .PP -For a list of standard message digest algorithm names, see Java Security -Standard Algorithm Names. +For a list of standard signature algorithm names, see the Java Security +Standard Algorithm Names Specification. .RE .TP \f[V]-verify\f[R] @@ -946,8 +949,8 @@ If this option isn\[aq]t specified, SHA-384 will be used. .PP See \f[B]Supported Algorithms\f[R]. .PP -For a list of standard message digest algorithm names, see Java Security -Standard Algorithm Names. +For a list of standard message digest algorithm names, see the Java +Security Standard Algorithm Names Specification. .RE .TP \f[V]-internalsf\f[R] diff --git a/src/jdk.javadoc/share/man/javadoc.1 b/src/jdk.javadoc/share/man/javadoc.1 index ad119c1dca3..a6437c0288b 100644 --- a/src/jdk.javadoc/share/man/javadoc.1 +++ b/src/jdk.javadoc/share/man/javadoc.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JAVADOC" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JAVADOC" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP @@ -98,13 +98,13 @@ When you document individual source files, pass in a list of Java source file names. .SS Conformance .PP -The Standard Doclet does not validate the content of documentation +The standard doclet does not validate the content of documentation comments for conformance, nor does it attempt to correct any errors in documentation comments. Anyone running javadoc is advised to be aware of the problems that may arise when generating non-conformant output or output containing executable content, such as JavaScript. -The Standard Doclet does provide the \f[B]DocLint\f[R] feature to help +The standard doclet does provide the \f[B]DocLint\f[R] feature to help developers detect common problems in documentation comments; but it is also recommended to check the generated output with any appropriate conformance and other checking tools. @@ -120,7 +120,7 @@ For more details on security issues related to web pages, see the .PP \f[V]javadoc\f[R] supports command-line options for both the main \f[V]javadoc\f[R] tool and the currently selected doclet. -The Standard Doclet is used if no other doclet is specified. +The standard doclet is used if no other doclet is specified. .PP GNU-style options (that is, those beginning with \f[V]--\f[R]) can use an equal sign (\f[V]=\f[R]) instead of whitespace characters to separate @@ -195,9 +195,9 @@ This doclet defines the content and formats the output. If the \f[V]-doclet\f[R] option isn\[aq]t used, then the \f[V]javadoc\f[R] tool uses the standard doclet for generating the default HTML format. -This class must contain the \f[V]start(Root)\f[R] method. -The path to this starting class is defined by the \f[V]-docletpath\f[R] -option. +This class must implement the \f[V]jdk.javadoc.doclet.Doclet\f[R] +interface. +The path to this class is defined by the \f[V]-docletpath\f[R] option. .TP \f[V]-docletpath\f[R] \f[I]path\f[R] Specifies where to find doclet class files (specified with the @@ -206,9 +206,9 @@ If the starting class file is in a JAR file, then this option specifies the path to that JAR file. You can specify an absolute path or a path relative to the current directory. -If \f[V]classpathlist\f[R] contains multiple paths or JAR files, then -they should be separated with a colon (\f[V]:\f[R]) on Linux and a -semi-colon (\f[V];\f[R]) on Windows. +If \f[V]path\f[R] contains multiple paths or JAR files, then they should +be separated with a colon (\f[V]:\f[R]) on Linux and macOS, and a +semicolon (\f[V];\f[R]) on Windows. This option isn\[aq]t necessary when the \f[V]doclet\f[R] starting class is already in the search path. .TP @@ -224,6 +224,7 @@ The following example would include \f[V]java.io\f[R], exclude packages rooted at \f[V]java.net\f[R] and \f[V]java.lang\f[R]. Notice that these examples exclude \f[V]java.lang.ref\f[R], which is a subpackage of \f[V]java.lang\f[R]. +Arguments are separated by colons on all operating systems. .IP \[bu] 2 \f[B]Linux and macOS:\f[R] .RS 2 @@ -246,7 +247,7 @@ javadoc -sourcepath \[rs]user\[rs]src -subpackages java -exclude java.net:java.l .RE .RE .TP -\f[V]--expand-requires\f[R] \f[I]value\f[R] +\f[V]--expand-requires\f[R] (\f[V]transitive\f[R]|\f[V]all\f[R]) Instructs the javadoc tool to expand the set of modules to be documented. By default, only the modules given explicitly on the command line are @@ -331,8 +332,8 @@ them easier to view. It also suppresses the \f[V]version\f[R] string. .TP \f[V]--show-members\f[R] \f[I]value\f[R] -Specifies which members (fields or methods) are documented, where -\f[I]value\f[R] can be any of the following: +Specifies which members (fields, methods, or constructors) are +documented, where \f[I]value\f[R] can be any of the following: .RS .IP \[bu] 2 \f[V]public\f[R] --- shows only public members @@ -350,7 +351,7 @@ Specifies the documentation granularity of module declarations, where \f[I]value\f[R] can be \f[V]api\f[R] or \f[V]all\f[R]. .TP \f[V]--show-packages\f[R] \f[I]value\f[R] -Specifies which modules packages are documented, where \f[I]value\f[R] +Specifies which module packages are documented, where \f[I]value\f[R] can be \f[V]exported\f[R] or \f[V]all\f[R] packages. .TP \f[V]--show-types\f[R] \f[I]value\f[R] @@ -484,15 +485,14 @@ javadoc --add-stylesheet new_stylesheet_1.css --add-stylesheet new_stylesheet_2. .RE .TP \f[V]--allow-script-in-comments\f[R] -Allow JavaScript in options and comments. +Allow JavaScript in documentation comments, and options whose value is +\f[I]html-code\f[R]. .TP \f[V]-author\f[R] Includes the \f[V]\[at]author\f[R] text in the generated docs. .TP \f[V]-bottom\f[R] \f[I]html-code\f[R] -Specifies the text to be placed at the bottom of each output file. -The text is placed at the bottom of the page, underneath the lower -navigation bar. +Specifies the text to be placed at the bottom of each generated page. The text can contain HTML tags and white space, but when it does, the text must be enclosed in quotation marks. Use escape characters for any internal quotation marks within text. @@ -591,19 +591,18 @@ javadoc -docencoding \[dq]iso-8859-1\[dq] mypackage .RE .TP \f[V]-docfilessubdirs\f[R] -Recursively copies doc-file subdirectories. -Enables deep copying of doc-files directories. +Enables deep copying of \f[V]doc-files\f[R] directories. Subdirectories and all contents are recursively copied to the destination. For example, the directory \f[V]doc-files/example/images\f[R] and all of its contents are copied. -The \f[B]\f[VB]-excludedocfilessubdir\f[B]\f[R] option can be used to -exclude specific subdirectories. +Use the \f[B]\f[VB]-excludedocfilessubdir\f[B]\f[R] option to restrict +the subdirectories to be copied. .TP \f[V]-doctitle\f[R] \f[I]html-code\f[R] Specifies the title to place near the top of the overview summary file. The text specified in the \f[V]title\f[R] tag is placed as a centered, -level-one heading directly beneath the top navigation bar. +level-one heading directly beneath the navigation bar. The \f[V]title\f[R] tag can contain HTML tags and white space, but when it does, you must enclose the title in quotation marks. Additional quotation marks within the \f[V]title\f[R] tag must be @@ -613,20 +612,13 @@ For example, .TP \f[V]-excludedocfilessubdir\f[R] \f[I]name1\f[R]\f[V],\f[R]\f[I]name2...\f[R] Excludes any subdirectories with the given names when recursively -copying doc-file subdirectories. +copying \f[V]doc-files\f[R] subdirectories. See \f[B]\f[VB]-docfilessubdirs\f[B]\f[R]. For historical reasons, \f[V]:\f[R] can be used anywhere in the argument as a separator instead of \f[V],\f[R]. .TP \f[V]-footer\f[R] \f[I]html-code\f[R] -Specifies the footer text to be placed at the bottom of each output -file. -The\f[V]html-code\f[R] value is placed to the right of the lower -navigation bar. -The \f[V]html-code\f[R] value can contain HTML tags and white space, but -when it does, the \f[V]html-code\f[R] value must be enclosed in -quotation marks. -Use escape characters for any internal quotation marks within a footer. +This option is no longer supported and reports a warning. .TP \f[V]-group\f[R] \f[I]name\f[R] \f[I]p1\f[R]\f[V],\f[R]\f[I]p2...\f[R] Group the specified packages together in the Overview page. @@ -635,7 +627,7 @@ in the argument instead of \f[V],\f[R]. .TP \f[V]-header\f[R] \f[I]html-code\f[R] Specifies the header text to be placed at the top of each output file. -The header is placed to the right of the upper navigation bar. +The header is placed to the right of the navigation bar. The \f[V]header\f[R] can contain HTML tags and white space, but when it does, the \f[V]header\f[R] must be enclosed in quotation marks. Use escape characters for internal quotation marks within a header. @@ -643,39 +635,10 @@ For example, \f[V]javadoc -header \[dq]<b>My Library</b><br>v1.0\[dq] com.mypackage\f[R]. .TP \f[V]-helpfile\f[R] \f[I]filename\f[R] -Includes the file that links to the \f[B]HELP\f[R] link in the top and -bottom navigation bars . -Without this option, the \f[V]javadoc\f[R] tool creates a help file -\f[V]help-doc.html\f[R] that is hard-coded in the \f[V]javadoc\f[R] -tool. -This option lets you override the default. -The \f[I]filename\f[R] can be any name and isn\[aq]t restricted to -\f[V]help-doc.html\f[R]. -The \f[V]javadoc\f[R] tool adjusts the links in the navigation bar -accordingly. -For example: -.RS -.IP \[bu] 2 -\f[B]Linux and macOS:\f[R] -.RS 2 -.IP -.nf -\f[CB] -javadoc -helpfile /home/user/myhelp.html java.awt -\f[R] -.fi -.RE -.IP \[bu] 2 -\f[B]Windows:\f[R] -.RS 2 -.IP -.nf -\f[CB] -javadoc -helpfile C:\[rs]user\[rs]myhelp.html java.awt -\f[R] -.fi -.RE -.RE +Specifies a file containing the text that will be displayed when the +\f[B]HELP\f[R] link in the navigation bar is clicked. +If this option is not given, the \f[V]javadoc\f[R] tool creates a +default page that will be used. .TP \f[V]-html5\f[R] This option is a no-op and is just retained for backwards compatibility. @@ -698,7 +661,8 @@ The \f[V]<meta>\f[R] tags include the fully qualified name of the class and the unqualified names of the fields and methods. Constructors aren\[aq]t included because they are identical to the class name. -For example, the class \f[V]String\f[R] starts with these keywords: +For example, the page for the class \f[V]String\f[R] includes these +keywords: .RS .IP .nf @@ -706,7 +670,7 @@ For example, the class \f[V]String\f[R] starts with these keywords: <meta name=\[dq]keywords\[dq] content=\[dq]java.lang.String class\[dq]> <meta name=\[dq]keywords\[dq] content=\[dq]CASE_INSENSITIVE_ORDER\[dq]> <meta name=\[dq]keywords\[dq] content=\[dq]length()\[dq]> -<meta name=\[dq]keywords\[dq] content=\[dq]charAt()\[dq]> +<meta name=\[dq]keywords\[dq] content=\[dq]isEmpty()\[dq]> \f[R] .fi .RE @@ -740,7 +704,7 @@ The \f[V]javadoc\f[R] tool reads the names from the appropriate list file and then links to the packages or modules at that URL. .PP When the \f[V]javadoc\f[R] tool runs, the \f[I]url\f[R] value is copied -into the \f[V]<A HREF>\f[R] links that are created. +into the \f[V]<a href>\f[R] links that are created. Therefore, \f[I]url\f[R] must be the URL to the directory and not to a file. .PP @@ -942,16 +906,15 @@ This is useful when your source code contains no deprecated APIs, and you want to make the navigation bar cleaner. .TP \f[V]-nohelp\f[R] -Omits the HELP link in the navigation bar at the top of each page of -output. +Omits the \f[B]HELP\f[R] link in the navigation bar at the top of each +generated page. .TP \f[V]-noindex\f[R] Omits the index from the generated documents. The index is produced by default. .TP \f[V]-nonavbar\f[R] -Prevents the generation of the navigation bar, header, and footer, that -are usually found at the top and bottom of the generated pages. +Prevents the generation of the navigation bar and header. The \f[V]-nonavbar\f[R] option has no effect on the \f[V]-bottom\f[R] option. The \f[V]-nonavbar\f[R] option is useful when you are interested only in @@ -994,17 +957,16 @@ associated with the \f[V]\[at]since\f[R] tags. Suppresses the time stamp, which is hidden in an HTML comment in the generated HTML near the top of each page. The \f[V]-notimestamp\f[R] option is useful when you want to run the -\f[V]javadoc\f[R] tool on two source bases and get the differences -between \f[V]diff\f[R] them, because it prevents time stamps from -causing a \f[V]diff\f[R] (which would otherwise be a \f[V]diff\f[R] on -every page). +\f[V]javadoc\f[R] tool on two source bases and compare them, because it +prevents time stamps from causing a difference (which would otherwise be +a difference on every page). The time stamp includes the \f[V]javadoc\f[R] tool release number. .TP \f[V]-notree\f[R] Omits the class and interface hierarchy pages from the generated documents. -These are the pages you reach using the Tree button in the navigation -bar. +These are the pages you reach using the \f[B]TREE\f[R] link in the +navigation bar. The hierarchy is produced by default. .TP \f[V]--override-methods\f[R] (\f[V]detail\f[R]|\f[V]summary\f[R]) @@ -1020,8 +982,8 @@ A relative path specified with the file name is relative to the current working directory. .RS .PP -While you can use any name you want for the \f[V]filename\f[R] value and -place it anywhere you want for the path, it is typical to name it +While you can use any name you want for the \f[I]filename\f[R] value and +place it anywhere you want, it is typical to name it \f[V]overview.html\f[R] 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, because @@ -1029,7 +991,8 @@ the \f[V]-sourcepath\f[R] option points to this file. .IP \[bu] 2 \f[B]Linux and macOS:\f[R] For example, if the source tree for the \f[V]java.lang\f[R] package is \f[V]src/classes/java/lang/\f[R], then -you could place the overview file at src/classes/overview.html. +you could place the overview file at +\f[V]src/classes/overview.html\f[R]. .IP \[bu] 2 \f[B]Windows:\f[R] For example, if the source tree for the \f[V]java.lang\f[R] package is @@ -1042,8 +1005,8 @@ The title on the overview page is set by \f[V]-doctitle\f[R]. .RE .TP \f[V]-serialwarn\f[R] -Generates compile-time warnings for missing \f[V]\[at]serial\f[R] tags. -By default, Javadoc generates no serial warnings. +Reports compile-time warnings for missing \f[V]\[at]serial\f[R] tags. +By default, Javadoc reports no serial warnings. Use this option to display the serial warnings, which helps to properly document default serializable fields and \f[V]writeExternal\f[R] methods. @@ -1055,8 +1018,8 @@ the specified \f[I]release\f[R]s. .PP If the \f[V]\[at]since\f[R] tag in the \f[V]javadoc\f[R] comment of an element in the documented source code matches a \f[I]release\f[R] passed -as option argument, information about the element and the release it was -added in is included in a \[dq]New API\[dq] page. +as the option argument, information about the element and the release it +was added in is included in a \[dq]New API\[dq] page. .PP If the \[dq]Deprecated API\[dq] page is generated and the \f[V]since\f[R] element of the \f[V]java.lang.Deprecated\f[R] annotation @@ -1079,7 +1042,7 @@ Specifies the search paths for finding files for external snippets. The \f[I]snippetpathlist\f[R] can contain multiple paths by separating them with the platform path separator (\f[V];\f[R] on Windows; \f[V]:\f[R] on other platforms.) -The Standard Doclet first searches the \f[V]snippet-files\f[R] +The standard doclet first searches the \f[V]snippet-files\f[R] subdirectory in the package containing the snippet, and then searches all the directories in the given list. .TP @@ -1099,7 +1062,7 @@ letter, plus a file for any index entries that start with non-alphabetical symbols. .TP \f[V]-tag\f[R] \f[I]name\f[R]:\f[I]locations\f[R]:\f[I]header\f[R] -Specifies single argument custom tags. +Specifies a custom tag with a single argument. For the \f[V]javadoc\f[R] tool to spell-check tag names, it is important to include a \f[V]-tag\f[R] option for every custom tag that is present in the source code, disabling (with \f[V]X\f[R]) those that aren\[aq]t @@ -1200,7 +1163,7 @@ Specifies the text to be placed at the top of each output file. \f[V]-use\f[R] Creates class and package usage pages. Includes one Use page for each documented class and package. -The page describes what packages, classes, methods, constructors and +The page describes what packages, classes, methods, constructors, and fields use any API of the specified 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 @@ -1213,15 +1176,15 @@ page for \f[V]String\f[R]. This documents only uses of the API, not the implementation. When a method uses \f[V]String\f[R] in its implementation, but doesn\[aq]t take a string as an argument or return a string, that -isn\[aq]t considered a use of \f[V]String\f[R].To access the generated -Use page, go to the class or package and click the \f[B]Use link\f[R] in -the navigation bar. +isn\[aq]t considered a use of \f[V]String\f[R]. +To access the generated Use page, go to the class or package and click +the \f[B]USE\f[R] link in the navigation bar. .TP \f[V]-version\f[R] Includes the version text in the generated docs. This text is omitted by default. To find out what version of the \f[V]javadoc\f[R] tool you are using, -use the \f[V]-J-version\f[R] option. +use the \f[V]--version\f[R] option (with two hyphens). .TP \f[V]-windowtitle\f[R] \f[I]title\f[R] Specifies the title to be placed in the HTML \f[V]<title>\f[R] tag. @@ -1239,7 +1202,7 @@ For example, \f[V]javadoc -windowtitle \[dq]My Library\[dq] com.mypackage\f[R]. .SS Extra Options for the Standard Doclet .PP -The following are additional options provided by the Standard Doclet and +The following are additional options provided by the standard doclet and are subject to change without notice. Additional options are less commonly used or are otherwise regarded as advanced. @@ -1276,7 +1239,7 @@ Every other argument is interpreted as directory from which to copy the legal files. .TP \f[V]--no-frames\f[R] -This option is a no-op and is just retained for backwards compatibility. +This option is no longer supported and reports a warning. .TP \f[V]-Xdoclint\f[R] Enables recommended checks for problems in documentation comments. @@ -1289,7 +1252,7 @@ For more details, see \f[B]DocLint\f[R]. .RE .TP \f[V]-Xdoclint:\f[R]\f[I]flag\f[R],\f[I]flag\f[R],... -Enable or disable specific checks for different kinds of issues in +Enables or disables specific checks for different kinds of issues in documentation comments. .RS .PP @@ -1454,7 +1417,7 @@ arguments for an \f[V]\[at]SuppressWarnings\f[R] annotation. .PP where \f[I]LIST\f[R] is a comma-separated list of one or more of \f[V]accessibility\f[R], \f[V]html\f[R], \f[V]missing\f[R], -\f[V]syntax\f[R], \f[V]reference\f[R]. +\f[V]reference\f[R], \f[V]syntax\f[R]. .PP The names in \f[I]LIST\f[R] are the same \f[B]group\f[R] names supported by the command-line \f[V]-Xdoclint\f[R] option for \f[V]javac\f[R] and @@ -1501,7 +1464,7 @@ that checks the content of documentation comments, as found in source files. In contrast, downstream validation tools can be used to validate the output generated from those documentation comments by \f[V]javadoc\f[R] -and the Standard Doclet. +and the standard doclet. .PP Although there is some overlap in functionality, the two mechanisms are different and each has its own strengths and weaknesses. @@ -1509,7 +1472,7 @@ different and each has its own strengths and weaknesses. Downstream validation tools can check the end result of any generated documentation, as it will be seen by the end user. This includes content from all sources, including documentation -comments, the Standard Doclet itself, user-provided taglets, and content +comments, the standard doclet itself, user-provided taglets, and content supplied via command-line options. Because such tools are analyzing complete HTML pages, they can do more complete checks than can DocLint. @@ -1526,7 +1489,7 @@ that downstream tools cannot detect, such as missing comments, using an \f[V]\[at]param\f[R] tag describing a non-existent parameter. But by its nature, DocLint cannot report on problems such as missing links, or errors in user-provided custom taglets, or problems in the -Standard Doclet itself. +standard doclet itself. It also cannot reliably detect errors in documentation comments at the boundaries between content in a documentation comment and content generated by a custom taglet. diff --git a/src/jdk.jcmd/share/man/jcmd.1 b/src/jdk.jcmd/share/man/jcmd.1 index 4157cf600e1..f33f7d2cb1e 100644 --- a/src/jdk.jcmd/share/man/jcmd.1 +++ b/src/jdk.jcmd/share/man/jcmd.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JCMD" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JCMD" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jcmd/share/man/jinfo.1 b/src/jdk.jcmd/share/man/jinfo.1 index ab87b21ab25..fc87807c6fe 100644 --- a/src/jdk.jcmd/share/man/jinfo.1 +++ b/src/jdk.jcmd/share/man/jinfo.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JINFO" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JINFO" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jcmd/share/man/jmap.1 b/src/jdk.jcmd/share/man/jmap.1 index 84e8abd7f0b..4865f43d1c4 100644 --- a/src/jdk.jcmd/share/man/jmap.1 +++ b/src/jdk.jcmd/share/man/jmap.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JMAP" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JMAP" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jcmd/share/man/jps.1 b/src/jdk.jcmd/share/man/jps.1 index 65284dd8efc..be506be2e82 100644 --- a/src/jdk.jcmd/share/man/jps.1 +++ b/src/jdk.jcmd/share/man/jps.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JPS" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JPS" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jcmd/share/man/jstack.1 b/src/jdk.jcmd/share/man/jstack.1 index d865d38138d..9effcb0902f 100644 --- a/src/jdk.jcmd/share/man/jstack.1 +++ b/src/jdk.jcmd/share/man/jstack.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JSTACK" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JSTACK" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jcmd/share/man/jstat.1 b/src/jdk.jcmd/share/man/jstat.1 index d62916c5c04..dd7d3832908 100644 --- a/src/jdk.jcmd/share/man/jstat.1 +++ b/src/jdk.jcmd/share/man/jstat.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JSTAT" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JSTAT" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jconsole/share/man/jconsole.1 b/src/jdk.jconsole/share/man/jconsole.1 index 5b61f92e6fa..ce1f948e6f1 100644 --- a/src/jdk.jconsole/share/man/jconsole.1 +++ b/src/jdk.jconsole/share/man/jconsole.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JCONSOLE" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JCONSOLE" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jdeps/share/man/javap.1 b/src/jdk.jdeps/share/man/javap.1 index 46d83c90f45..68290d25bfb 100644 --- a/src/jdk.jdeps/share/man/javap.1 +++ b/src/jdk.jdeps/share/man/javap.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JAVAP" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JAVAP" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jdeps/share/man/jdeprscan.1 b/src/jdk.jdeps/share/man/jdeprscan.1 index c252198d432..ac850cf78de 100644 --- a/src/jdk.jdeps/share/man/jdeprscan.1 +++ b/src/jdk.jdeps/share/man/jdeprscan.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JDEPRSCAN" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JDEPRSCAN" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jdeps/share/man/jdeps.1 b/src/jdk.jdeps/share/man/jdeps.1 index 32eb438b520..53891441665 100644 --- a/src/jdk.jdeps/share/man/jdeps.1 +++ b/src/jdk.jdeps/share/man/jdeps.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JDEPS" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JDEPS" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jdi/share/man/jdb.1 b/src/jdk.jdi/share/man/jdb.1 index d53d8b7ac6e..530c9bed6a1 100644 --- a/src/jdk.jdi/share/man/jdb.1 +++ b/src/jdk.jdi/share/man/jdb.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JDB" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JDB" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jfr/share/man/jfr.1 b/src/jdk.jfr/share/man/jfr.1 index 576721fe21a..c6a568582c0 100644 --- a/src/jdk.jfr/share/man/jfr.1 +++ b/src/jdk.jfr/share/man/jfr.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JFR" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JFR" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jlink/share/man/jlink.1 b/src/jdk.jlink/share/man/jlink.1 index a8aaf2982fe..1a0b79a39c1 100644 --- a/src/jdk.jlink/share/man/jlink.1 +++ b/src/jdk.jlink/share/man/jlink.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JLINK" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JLINK" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jlink/share/man/jmod.1 b/src/jdk.jlink/share/man/jmod.1 index 74b73cd9d92..b26685615ed 100644 --- a/src/jdk.jlink/share/man/jmod.1 +++ b/src/jdk.jlink/share/man/jmod.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JMOD" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JMOD" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jpackage/share/man/jpackage.1 b/src/jdk.jpackage/share/man/jpackage.1 index ec26b28e852..3f5e062ee6c 100644 --- a/src/jdk.jpackage/share/man/jpackage.1 +++ b/src/jdk.jpackage/share/man/jpackage.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JPACKAGE" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JPACKAGE" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jshell/share/man/jshell.1 b/src/jdk.jshell/share/man/jshell.1 index 8651b703214..76ea665e9ef 100644 --- a/src/jdk.jshell/share/man/jshell.1 +++ b/src/jdk.jshell/share/man/jshell.1 @@ -36,7 +36,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JSHELL" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JSHELL" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP diff --git a/src/jdk.jstatd/share/man/jstatd.1 b/src/jdk.jstatd/share/man/jstatd.1 index 81e433bced5..cbbaeaf49f2 100644 --- a/src/jdk.jstatd/share/man/jstatd.1 +++ b/src/jdk.jstatd/share/man/jstatd.1 @@ -35,7 +35,7 @@ . ftr VB CB . ftr VBI CBI .\} -.TH "JSTATD" "1" "2024" "JDK 22-ea" "JDK Commands" +.TH "JSTATD" "1" "2024" "JDK 23-ea" "JDK Commands" .hy .SH NAME .PP