For review, changes to java.1 nroff page as part of OpenJDK 8u40 nroff review

Tue Oct 14 22:29:51 UTC 2014

Changes look good.

Thanks,
Vladimir

On 10/14/14 3:27 PM, raymond gallardo wrote:
> Hi all,
>
> The following changes to the java.1 nroff pages have been made as part
> of the OpenJDK 8u40 review. The file itself can be obtained here:
>
> http://cr.openjdk.java.net/~rgallard/java.1
>
> =====================================
> [The sentence "*This option is ignored when tiered compilation is
> enabled; see the option -XX:+TieredCompilation." was added.]*
>
> -XX:CompileThreshold=invocations
> Sets the number of interpreted method invocations before compilation. By
> default, in the server JVM, the JIT compiler performs 10,000 interpreted
> method invocations to gather information for efficient compilation. For
> the client JVM, the default setting is 1,500 invocations. *This option
> is ignored when tiered compilation is enabled; see the option
> -XX:+TieredCompilation. *The following example shows how to set the
> number of interpreted method invocations to 5,000:
>
> -XX:CompileThreshold=5000
>
> You can completely disable interpretation of Java methods before
> compilation by specifying the -Xcomp option.
>
> =====================================
>
> [The sentence "*The initial code cache size should be not less than the
> system's minimal memory page size." was added.]*
>
> -XX:InitialCodeCacheSize=size
> Sets the initial code cache size (in bytes). Append the letter k or K to
> indicate kilobytes, m or M to indicate megabytes, g or G to indicate
> gigabytes. The default value is set to 500 KB. *The initial code cache
> size should be not less than the system's minimal memory page size.*The
> following example shows how to set the initial code cache size to 32 KB:
>
> -XX:InitialCodeCacheSize=32k
>
> =====================================
> [The sentences "*This option has a limit of 2 GB; otherwise, an error is
> generated. The maximum code cache size should not be less than the
> initial code cache size; see the option -XX:InitialCodeCacheSize" were
> added.]*
>
> -XX:ReservedCodeCacheSize=size
> Sets the maximum code cache size (in bytes) for JIT-compiled code.
> Append the letter k or K to indicate kilobytes, m or M to indicate
> megabytes, g or G to indicate gigabytes. *This option has a limit of 2
> GB; otherwise, an error is generated. The maximum code cache size should
> not be less than the initial code cache size; see the option
> -XX:InitialCodeCacheSize.*This option is equivalent to -Xmaxjitcodesize.
>
> =====================================
> ["-XX:+UseRTMLocking" was changed from "-XX:UseRTMLocking".]
>
> -XX:+UseRTMDeopt
> Auto-tunes RTM locking depending on the abort ratio. This ratio is
> specified by -XX:RTMAbortRatio option. If the number of aborted
> transactions exceeds the abort ratio, then the method containing the
> lock will be deoptimized and recompiled with all locks as normal locks.
> This option is disabled by default. The *-XX:+UseRTMLocking*option must
> be enabled.
>
> =====================================
>
> Thanks,
> --Raymond
>
> On 2014-10-10 2:53 PM, raymond gallardo wrote:
>> Hi all,
>>
>> Just a reminder that the nroff files for 8u40 are up for review.
>> Please send us your feedback by the end of the day today, Friday,
>> October, 10.
>>
>> Thanks,
>> --The Java SE Documentation team
>>
>> On 2014-10-08 2:12 PM, raymond gallardo wrote:
>>>
>>>
>>> Hello Reviewers,
>>>
>>> As part of the OpenJDK review processes, and the next Java SE 8u40
>>> release, the OpenJDK 8 nroff files for Java tools are up for review,
>>> which is available here as a zip file:
>>>
>>> http://cr.openjdk.java.net/~rgallard/openjdk_nroff_8u40.zip
>>>
>>> You can obtain the webrev here:
>>>
>>> http://cr.openjdk.java.net/~rgallard/openjdk_webrev_8u40.zip
>>>
>>> Please provide your feedback by Friday, October 10, 2014.
>>>
>>> The following sections describe what kinds of review comments we're
>>> looking for and what has changed for Java SE 8u40. Please contact us if
>>> you have any questions.
>>>
>>>     Summary of Changes
>>>     Scope of Review
>>>     Provide Feedback
>>>     How to View a Man Page
>>>
>>> Summary of Changes
>>>
>>> Technical content changes related to JDK 8 features have been made.
>>> These changes have already been reviewed by the engineer responsible for
>>> each feature.
>>>
>>> HTML documentation for Java tools has also been generated, which has the
>>> same content as the nroff files up for review, and which will be
>>> available on download.java.net.
>>>
>>> The following lists significant changes made to the Java tool nroff
>>> pages for this release as well as the engineer who reviewed the content.
>>>
>>> java:
>>>
>>> JDK-8054382 : (JDK-8054376 : Move RTM flags from Experimental to
>>> Product) Update RTM documentation, staffan.friberg at oracle.com and
>>> vladimir.kozlov at oracle.com.
>>> JDK-8043965 : Xverify:remote description is wrong, David Buck
>>> JDK-8040180 : Extend and improve documentation about Large pages,
>>> staffan.friberg at oracle.com and stefan.karlsson at oracle.com
>>> JDK-8040176 : Document -XX:ObjectAlignmentInBytes flag, Vladimir Kozlov
>>> JDK-8037590 : The name for PerfDataSaveToFile flag is incorrect in
>>> HotSpot VM Options document, masato.yoshida at oracle.com
>>> JDK-8032725 : Description of default maximum heap size need correction,
>>> masato.yoshida at oracle.com
>>>
>>> keytool:
>>>
>>> JDK-8050813 : Option values are not italicized on JDK 8 keytool
>>> documentation page, Jason Uh
>>>
>>> javapackager and javafxpackager (Note that changes to javapackager and
>>> javafxpackager will not appear in the webrev because they will be pushed
>>> to a different repository):
>>>
>>> RT-37898, Danno Ferrin
>>> RT-37876, Danno Ferrin
>>>
>>> javac:
>>>
>>> JDK-8016641 : Cross compilation not as documented, Maurizio Cimadamore
>>>
>>> jjs:
>>>
>>> JDK-8041730 : Nashorn documentation bug, Sundararajan Athijegannathan
>>> JDK-8038292 : whitespace missing in examples in jjs tool doc page,
>>> Sundararajan Athijegannathan
>>>
>>> policytool:
>>>
>>> JDK-8059076 : Spacing bug in policytool.html
>>>
>>> jstat:
>>>
>>> JDK-8040079 : jstat documentation needs to be updated for metaspace,
>>> erik.helin at oracle.com
>>>
>>> javadoc:
>>>
>>> New -javafx option added
>>>
>>>
>>> Scope of Review
>>>
>>> Please provide a sanity check of content as opposed to reviewing the
>>> nroff markup itself.
>>>
>>> A line-by-line comparison between the html and nroff versions is not
>>> needed.
>>>
>>> Provide Feedback
>>>
>>> Please indicate your approval and provide feedback by e-mail by October
>>> 10, 2014.
>>>
>>> All feedback will be triaged. Severe technical inaccuracies and other
>>> small bugs will be fixed. Due to Java SE 8u40 release plan deadlines,
>>> bugs will be filed for large scale changes and will most likely be
>>> handled in a future update release.
>>>
>>> How To View A Man Page
>>>
>>> 1. Download the openjdk_nroff_8u40.zip file to a directory of your
>>> choice. (The exact zip file name will vary depending upon the exact man
>>> page bundle and creation date.)
>>>
>>> 2. Open a terminal window. Change to the directory that contains the zip
>>> file.
>>>
>>> 3. Extract the contents of the zip file as follows:
>>>
>>> $ unzip openjdk_nroff_8u40.zip
>>>
>>> This creates a sub-directory named openjdk_nroff_8u40 in the current
>>> directory.
>>>
>>> 4. Change directory to openjdk_nroff_8u40 as follows:
>>>
>>> $ cd openjdk_nroff_8u40
>>>
>>> View a man page with a command of the following form:
>>>
>>> $ man -M man <page name>
>>>
>>> For example, to view the javap man page, run the following command:
>>>
>>> $ man -M man javap
>>>
>>> Notes
>>>
>>> (Linux and OS X only.) The -t option to the man command will generate
>>> typeset output in PostScript format and send it to stdout:
>>>
>>> $ man -M man -t javap > javap.ps
>>>
>>> PostScript can be displayed using Preview (on Mac) and by the Gnome
>>> Document Viewer (Linux/Gnome). (On Solaris, the man -t option will send
>>> the output to a printer, which might not be what you want.)
>>>
>>> If bullets render as a funny character, set the remote character set to
>>> UTF-8. For example, if you are using PuTTY, an SSH and telnet client,
>>> you can specify the remote character set by selecting from the context
>>> menu Change Settings... > Window > Translation > Remote character set >
>>> UTF-8.
>>>
>>> Thank you,
>>> The Java SE 8 Documentation Team
>>>
>>>
>>>
>>
>