From robert.field at oracle.com  Mon May  6 15:20:22 2019
From: robert.field at oracle.com (Robert Field)
Date: Mon, 6 May 2019 08:20:22 -0700
Subject: RFR: JDK-8221759: Crash when completing "java.io.File.path"
In-Reply-To: <1a06ddad-b131-77ae-a6b3-61b5afe02058@oracle.com>
References: <1a06ddad-b131-77ae-a6b3-61b5afe02058@oracle.com>
Message-ID: <574106fc-f3cb-3d1d-3a8c-94eba63c1337@oracle.com>

Thumbs up!

-Robert


On 4/15/19 4:32 AM, Jan Lahoda wrote:
> Hi,
>
> Typing:
> java.io.File.path
> and pressing <tab> leads to a crash/exception. The root reason appears 
> to be that in addition to the expected completions (i.e. 
> 'pathSeparator' and 'pathSeparatorChar'), there is also a private 
> field of File, called "path". That is not accessible, so it is not 
> shown as a completion, but the "SourceCodeAnalysis.documentation" call 
> includes documentation for it, which ultimately leads to the crash.
>
> The proposed fix is to include the accessibility check also in the 
> "SourceCodeAnalysis.documentation" call, so that inaccessible elements 
> are ignored for documentation as they are for completion.
>
> Webrev: http://cr.openjdk.java.net/~jlahoda/8221759/webrev.00/
> JBS: https://bugs.openjdk.java.net/browse/JDK-8221759
>
> How does this look?
>
> Thanks,
> ??? Jan

From robert.field at oracle.com  Mon May 13 00:06:09 2019
From: robert.field at oracle.com (Robert Field)
Date: Sun, 12 May 2019 17:06:09 -0700
Subject: RFR 8223595: Consider updating jdk.jshell module description
Message-ID: <957ee40b-3206-c6a2-b9f3-2abf2222040c@oracle.com>

Please review....

Bug: https://bugs.openjdk.java.net/browse/JDK-8223595

sdiff -

   25
   26 /**
27 * This module provides support for
28 * Java Programming Language 'snippet' evaluating tools, such as
29 * Read-Eval-Print Loops (REPLs), including the <em>{@index jshell 
jshell tool}</em> tool.

   30  * Separate packages support building tools, configuring the execution of tools,
   31  * and programmatically launching the existing Java shell tool.


------------------------------------------------------------------------
------------------------------------------------------------------------

   25
   26 /**
27 * Defines the JShell API and provides the <em>{@index jshell jshell 
tool}</em> tool
28 * for evaluating snippets of Java code.
29 * The JShell API supports Java Programming Language 'snippet' 
evaluating tools,
30 * such as Read-Eval-Print Loops (REPLs).
   31  * Separate packages support building tools, configuring the execution of tools,
   32  * and programmatically launching the existing Java shell tool.

------------------------------------------------------------------------

Old module description:

jdk.jshell 
<https://download.java.net/java/early_access/jdk13/docs/api/jdk.jshell/module-summary.html> 
	
This module provides support for Java Programming Language 'snippet' 
evaluating tools, such as Read-Eval-Print Loops (REPLs), including 
the/jshell/tool.

New module description:

jdk.jshell 	
Defines the JShell API and provides the/jshell/tool for evaluating 
snippets of Java code.

Module doc:

Defines the JShell API and provides the/jshell/tool for evaluating 
snippets of Java code. The JShell API supports Java Programming Language 
'snippet' evaluating tools, such as Read-Eval-Print Loops (REPLs). 
Separate packages support building tools, configuring the execution of 
tools, and programmatically launching the existing Java shell tool.

The|jdk.jshell|is the package for creating 'snippet' evaluating tools. 
Generally, this is only package that would be needed for creating tools.

The|jdk.jshell.spi|package specifies a Service Provider Interface (SPI) 
for defining execution engine implementations for tools based on 
the|jdk.jshell|API. The|jdk.jshell.execution|package provides standard 
implementations of|jdk.jshell.spi|interfaces and supporting code. It 
also serves as a library of functionality for defining new execution 
engine implementations.

The|jdk.jshell.tool|package supports programmatically launching 
the/jshell/tool.

The|jdk.jshell.execution|package contains implementations of the 
interfaces in|jdk.jshell.spi|. Otherwise, the four packages are 
independent, operate at different levels, and do not share functionality 
or definitions.

Tool Guides:
    jshell
    <https://docs.oracle.com/pls/topic/lookup?ctx=javase13&id=jshell_tool_reference>

Since:
    9

-Robert



From sormuras at gmail.com  Mon May 13 16:03:18 2019
From: sormuras at gmail.com (Christian Stein)
Date: Mon, 13 May 2019 18:03:18 +0200
Subject: JShell proposal: /exit_if {predicate}
Message-ID: <CAJi8+g7Kpjahh87DHj24WX0MTh8AWY7B8XjUupJ0LgHtQTWrHA@mail.gmail.com>

Hi!

I often find me writing JShell-based scripts like [1] that chain
calls to various tools or functions. To achieve a "fail-fast" on
first error behaviour, I store an "all-is-okay" flag and guard
each tool call by a checking the flag for a zero, indicating all
is still okay, proceed with next call.

It'd be super convenient if there was a JShell command that
wraps that feature. Something like the following pseudo-code:

/exit_if 5 - 4 == 2
/exit_if Files.isSameFile()

Cheers,
Christian

[1] https://github.com/sormuras/make-java/blob/master/build.jsh

From brian.goetz at oracle.com  Mon May 13 16:08:21 2019
From: brian.goetz at oracle.com (Brian Goetz)
Date: Mon, 13 May 2019 12:08:21 -0400
Subject: JShell proposal: /exit_if {predicate}
In-Reply-To: <CAJi8+g7Kpjahh87DHj24WX0MTh8AWY7B8XjUupJ0LgHtQTWrHA@mail.gmail.com>
References: <CAJi8+g7Kpjahh87DHj24WX0MTh8AWY7B8XjUupJ0LgHtQTWrHA@mail.gmail.com>
Message-ID: <C8B79B5B-5FE1-4B6E-8730-545F586D55FD@oracle.com>

JShell was designed to be an interactive environment, not a batch runner.  Though I understand why you would want to apply it as such, features like this serve merely to dilute the design center, ultimately at the expense of its core mission.  

There is a story for batch execution: JEP 330 (https://openjdk.java.net/jeps/330 <https://openjdk.java.net/jeps/330>).  


> On May 13, 2019, at 12:03 PM, Christian Stein <sormuras at gmail.com> wrote:
> 
> Hi!
> 
> I often find me writing JShell-based scripts like [1] that chain
> calls to various tools or functions. To achieve a "fail-fast" on
> first error behaviour, I store an "all-is-okay" flag and guard
> each tool call by a checking the flag for a zero, indicating all
> is still okay, proceed with next call.
> 
> It'd be super convenient if there was a JShell command that
> wraps that feature. Something like the following pseudo-code:
> 
> /exit_if 5 - 4 == 2
> /exit_if Files.isSameFile()
> 
> Cheers,
> Christian
> 
> [1] https://github.com/sormuras/make-java/blob/master/build.jsh


From sormuras at gmail.com  Mon May 13 16:15:05 2019
From: sormuras at gmail.com (Christian Stein)
Date: Mon, 13 May 2019 18:15:05 +0200
Subject: JShell proposal: /exit_if {predicate}
In-Reply-To: <C8B79B5B-5FE1-4B6E-8730-545F586D55FD@oracle.com>
References: <CAJi8+g7Kpjahh87DHj24WX0MTh8AWY7B8XjUupJ0LgHtQTWrHA@mail.gmail.com>
 <C8B79B5B-5FE1-4B6E-8730-545F586D55FD@oracle.com>
Message-ID: <CAJi8+g5Ob7vAxmu-WuGZUOj+qcpj2xTwP40-T2946JPCVatX7A@mail.gmail.com>

On Mon, May 13, 2019 at 6:08 PM Brian Goetz <brian.goetz at oracle.com> wrote:

> JShell was designed to be an interactive environment, not a batch runner.
> Though I understand why you would want to apply it as such, features like
> this serve merely to dilute the design center, ultimately at the expense of
> its core mission.
>


Got it. But still... it'd be convenient.


> There is a story for batch execution: JEP 330 (
> https://openjdk.java.net/jeps/330).
>

If only `java {url}` was suppported.

At the moment, you can use `jshell https://bit.ly/make-java` [2] like a
charm, but `java {here_be_a_url_pointing_to_Make.java}` doesn't.

[2] https://github.com/sormuras/make-java#makejava

From robert.field at oracle.com  Mon May 13 23:25:15 2019
From: robert.field at oracle.com (Robert Field)
Date: Mon, 13 May 2019 16:25:15 -0700
Subject: RFR 8223595: Consider updating jdk.jshell module description
In-Reply-To: <957ee40b-3206-c6a2-b9f3-2abf2222040c@oracle.com>
References: <957ee40b-3206-c6a2-b9f3-2abf2222040c@oracle.com>
Message-ID: <46708ee4-29ea-6fac-87eb-f8da97e81773@oracle.com>

Version 01, after Alex's comment in the bug --

Bug: https://bugs.openjdk.java.net/browse/JDK-8223595


    src/jdk.jshell/share/classes/module-info.java

------------------------------------------------------------------------
*** 22,34 ****
    * or visit www.oracle.com if you need additional information or have any
    * questions.
    */
   
   /**
!  * This module provides support for
!  * Java Programming Language 'snippet' evaluating tools, such as
!  * Read-Eval-Print Loops (REPLs), including the <em>{@index jshell jshell tool}</em> tool.
    * Separate packages support building tools, configuring the execution of tools,
    * and programmatically launching the existing Java shell tool.
    * <p>
    *     The {@link jdk.jshell} is the package for creating 'snippet' evaluating tools.
    *     Generally, this is only package that would be needed for creating tools.
--- 22,35 ----
    * or visit www.oracle.com if you need additional information or have any
    * questions.
    */
   
   /**
!  * Defines the JShell API and provides the <em>{@index jshell jshell tool}</em> tool
!  * for evaluating snippets of Java code.
!  * The JShell API supports Java Programming Language 'snippet' evaluating tools,
!  * such as Read-Eval-Print Loops (REPLs).
    * Separate packages support building tools, configuring the execution of tools,
    * and programmatically launching the existing Java shell tool.
    * <p>
    *     The {@link jdk.jshell} is the package for creating 'snippet' evaluating tools.
    *     Generally, this is only package that would be needed for creating tools.


Old module description:

    jdk.jshell
    <https://docs.oracle.com/en/java/javase/12/docs/api/jdk.jshell/module-summary.html>
    	
    This module provides support for Java Programming Language 'snippet'
    evaluating tools, such as Read-Eval-Print Loops (REPLs), including
    the?jshell?tool.


New module description:

    jdk.jshell 	
    Provides the?jshell?tool for evaluating snippets of Java code, and
    defines a JDK-specific API for modeling and executing snippets.


Module doc:

    Provides the jshell?tool for evaluating snippets of Java code, and
    defines a JDK-specific API for modeling and executing snippets. The
    JShell API supports Java Programming Language 'snippet' evaluating
    tools, such as Read-Eval-Print Loops (REPLs). Separate packages
    support building tools, configuring the execution of tools, and
    programmatically launching the existing Java shell tool.

    The jdk.jshell?is the package for creating 'snippet' evaluating
    tools. Generally, this is only package that would be needed for
    creating tools.

    The jdk.jshell.spi?package specifies a Service Provider Interface
    (SPI) for defining execution engine implementations for tools based
    on the jdk.jshell?API. The jdk.jshell.execution?package provides
    standard implementations of jdk.jshell.spi?interfaces and supporting
    code. It also serves as a library of functionality for defining new
    execution engine implementations.

    The jdk.jshell.tool?package supports programmatically launching
    the?jshell?tool.

    The jdk.jshell.execution?package contains implementations of the
    interfaces in jdk.jshell.spi. Otherwise, the four packages are
    independent, operate at different levels, and do not share
    functionality or definitions.

    Tool Guides:
        jshell
        <https://docs.oracle.com/pls/topic/lookup?ctx=javase13&id=jshell_tool_reference>

    Since:
        9

-Robert


From jan.lahoda at oracle.com  Tue May 14 15:46:51 2019
From: jan.lahoda at oracle.com (Jan Lahoda)
Date: Tue, 14 May 2019 17:46:51 +0200
Subject: RFR 8223595: Consider updating jdk.jshell module description
In-Reply-To: <46708ee4-29ea-6fac-87eb-f8da97e81773@oracle.com>
References: <957ee40b-3206-c6a2-b9f3-2abf2222040c@oracle.com>
 <46708ee4-29ea-6fac-87eb-f8da97e81773@oracle.com>
Message-ID: <e0be7338-3a45-dc20-a3f0-3cbba29e108b@oracle.com>

Looks good to me.

Jan

On 14. 05. 19 1:25, Robert Field wrote:
> Version 01, after Alex's comment in the bug --
> 
> Bug: https://bugs.openjdk.java.net/browse/JDK-8223595
> 
> 
>  ?? src/jdk.jshell/share/classes/module-info.java
> 
> ------------------------------------------------------------------------
> *** 22,34 ****
>  ?? * or visit www.oracle.com if you need additional information or have 
> any
>  ?? * questions.
>  ?? */
>  ? /**
> !? * This module provides support for
> !? * Java Programming Language 'snippet' evaluating tools, such as
> !? * Read-Eval-Print Loops (REPLs), including the <em>{@index jshell 
> jshell tool}</em> tool.
>  ?? * Separate packages support building tools, configuring the 
> execution of tools,
>  ?? * and programmatically launching the existing Java shell tool.
>  ?? * <p>
>  ?? *???? The {@link jdk.jshell} is the package for creating 'snippet' 
> evaluating tools.
>  ?? *???? Generally, this is only package that would be needed for 
> creating tools.
> --- 22,35 ----
>  ?? * or visit www.oracle.com if you need additional information or have 
> any
>  ?? * questions.
>  ?? */
>  ? /**
> !? * Defines the JShell API and provides the <em>{@index jshell jshell 
> tool}</em> tool
> !? * for evaluating snippets of Java code.
> !? * The JShell API supports Java Programming Language 'snippet' 
> evaluating tools,
> !? * such as Read-Eval-Print Loops (REPLs).
>  ?? * Separate packages support building tools, configuring the 
> execution of tools,
>  ?? * and programmatically launching the existing Java shell tool.
>  ?? * <p>
>  ?? *???? The {@link jdk.jshell} is the package for creating 'snippet' 
> evaluating tools.
>  ?? *???? Generally, this is only package that would be needed for 
> creating tools.
> 
> 
> Old module description:
> 
>  ?? jdk.jshell
>     
> <https://docs.oracle.com/en/java/javase/12/docs/api/jdk.jshell/module-summary.html> 
> 
> 
>  ?? This module provides support for Java Programming Language 'snippet'
>  ?? evaluating tools, such as Read-Eval-Print Loops (REPLs), including
>  ?? the?jshell?tool.
> 
> 
> New module description:
> 
>  ?? jdk.jshell
>  ?? Provides the?jshell?tool for evaluating snippets of Java code, and
>  ?? defines a JDK-specific API for modeling and executing snippets.
> 
> 
> Module doc:
> 
>  ?? Provides the jshell?tool for evaluating snippets of Java code, and
>  ?? defines a JDK-specific API for modeling and executing snippets. The
>  ?? JShell API supports Java Programming Language 'snippet' evaluating
>  ?? tools, such as Read-Eval-Print Loops (REPLs). Separate packages
>  ?? support building tools, configuring the execution of tools, and
>  ?? programmatically launching the existing Java shell tool.
> 
>  ?? The jdk.jshell?is the package for creating 'snippet' evaluating
>  ?? tools. Generally, this is only package that would be needed for
>  ?? creating tools.
> 
>  ?? The jdk.jshell.spi?package specifies a Service Provider Interface
>  ?? (SPI) for defining execution engine implementations for tools based
>  ?? on the jdk.jshell?API. The jdk.jshell.execution?package provides
>  ?? standard implementations of jdk.jshell.spi?interfaces and supporting
>  ?? code. It also serves as a library of functionality for defining new
>  ?? execution engine implementations.
> 
>  ?? The jdk.jshell.tool?package supports programmatically launching
>  ?? the?jshell?tool.
> 
>  ?? The jdk.jshell.execution?package contains implementations of the
>  ?? interfaces in jdk.jshell.spi. Otherwise, the four packages are
>  ?? independent, operate at different levels, and do not share
>  ?? functionality or definitions.
> 
>  ?? Tool Guides:
>  ?????? jshell
>         
> <https://docs.oracle.com/pls/topic/lookup?ctx=javase13&id=jshell_tool_reference> 
> 
> 
>  ?? Since:
>  ?????? 9
> 
> -Robert
> 

From robert.field at oracle.com  Sat May 18 21:08:02 2019
From: robert.field at oracle.com (Robert Field)
Date: Sat, 18 May 2019 14:08:02 -0700
Subject: RFR 8080353: JShell: Better error message on attempting to add
 default method
Message-ID: <eb8be6c5-e90a-055f-0e0c-337faea355c8@oracle.com>

Please review...

Bug: https://bugs.openjdk.java.net/browse/JDK-8080353

Webrev: http://cr.openjdk.java.net/~rfield/8080353.webrev/

Thanks,
Robert



From joe.darcy at oracle.com  Sun May 19 19:36:55 2019
From: joe.darcy at oracle.com (Joe Darcy)
Date: Sun, 19 May 2019 12:36:55 -0700
Subject: JDK 13 RFR of JDK-8224175: Fix inconsistencies in @jls and @jvms tags
Message-ID: <478b540e-35a0-b9df-8bf3-c03b0422af8f@oracle.com>

Hello,

Thanks to some tooling developed by Jon Gibbons, inconsistencies in the 
section names and numbers in the @jls and @jvms javadoc tags in the jdk 
and the names and numbers of the current specifications have been 
identified. These inconsistencies should be fixed.

The names and numbers of the section titles in JLS and JVMS are *mostly* 
stable, but a few sections have changed most notably for the usage of 
@jls tags:

 ??? * 8.9 "Enum" -> "Enum Type" in Java SE 8
 ??? * 5.1.2 "Widening Primitive Conversions" -> "Widening Primitive 
*Conversion*" in Java SE 7

Two uses of "@jvms 5.3 Run-time package" refer to the term "Run-time 
package" defined in that section. The term was replaced by the section 
name in both cases.

In java.lang.SuppressWarnings, a reference to the section "5.5.2 Checked 
Casts and Unchecked Casts", which was removed in Java SE 9, was replaced 
with a reference to the enclosing section "5.5. Casting Contexts".

The usage of @jls in jshell was less consistent and has been regularized.

Full webrev at:

 ??? http://cr.openjdk.java.net/~darcy/8224175.0/

Patch below.

Thanks,

-Joe

--- old/src/java.base/share/classes/java/lang/Byte.java 2019-05-19 
12:16:26.705761266 -0700
+++ new/src/java.base/share/classes/java/lang/Byte.java 2019-05-19 
12:16:26.137761266 -0700
@@ -356,7 +356,7 @@
 ???? /**
 ????? * Returns the value of this {@code Byte} as a {@code short} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public short shortValue() {
 ???????? return (short)value;
@@ -365,7 +365,7 @@
 ???? /**
 ????? * Returns the value of this {@code Byte} as an {@code int} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public int intValue() {
 ???????? return (int)value;
@@ -374,7 +374,7 @@
 ???? /**
 ????? * Returns the value of this {@code Byte} as a {@code long} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public long longValue() {
 ???????? return (long)value;
@@ -383,7 +383,7 @@
 ???? /**
 ????? * Returns the value of this {@code Byte} as a {@code float} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public float floatValue() {
 ???????? return (float)value;
@@ -392,7 +392,7 @@
 ???? /**
 ????? * Returns the value of this {@code Byte} as a {@code double}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public double doubleValue() {
 ???????? return (double)value;
--- old/src/java.base/share/classes/java/lang/Class.java 2019-05-19 
12:16:27.597761266 -0700
+++ new/src/java.base/share/classes/java/lang/Class.java 2019-05-19 
12:16:27.161761266 -0700
@@ -999,7 +999,7 @@
 ????? *
 ????? * @since 9
 ????? * @spec JPMS
-???? * @jls 6.7? Fully Qualified Names
+???? * @jls 6.7 Fully Qualified Names
 ????? */
 ???? public String getPackageName() {
 ???????? String pn = this.packageName;
@@ -3910,7 +3910,8 @@
 ????? *???????? SecurityManager#checkPackageAccess s.checkPackageAccess()}
 ????? *???????? denies access to the package of the returned class
 ????? * @since 11
-???? * @jvms 4.7.28 and 4.7.29 NestHost and NestMembers attributes
+???? * @jvms 4.7.28 The {@code NestHost} Attribute
+???? * @jvms 4.7.29 The {@code NestMembers} Attribute
 ????? * @jvms 5.4.4 Access Control
 ????? */
 ???? @CallerSensitive
--- old/src/java.base/share/classes/java/lang/ClassLoader.java 
2019-05-19 12:16:28.429761266 -0700
+++ new/src/java.base/share/classes/java/lang/ClassLoader.java 
2019-05-19 12:16:28.041761266 -0700
@@ -222,7 +222,7 @@
 ? * or a fully qualified name as defined by
 ? * <cite>The Java&trade; Language Specification</cite>.
 ? *
- * @jls 6.7? Fully Qualified Names
+ * @jls 6.7 Fully Qualified Names
 ? * @jls 13.1 The Form of a Binary
 ? * @see????? #resolveClass(Class)
 ? * @since 1.0
@@ -2194,7 +2194,7 @@
 ????? * @revised 9
 ????? * @spec JPMS
 ????? *
-???? * @jvms 5.3 Run-time package
+???? * @jvms 5.3 Creation and Loading
 ????? * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">
 ????? *????? The JAR File Specification: Package Sealing</a>
 ????? */
@@ -2228,7 +2228,7 @@
 ????? * @throws? NullPointerException
 ????? *????????? if {@code name} is {@code null}.
 ????? *
-???? * @jvms 5.3 Run-time package
+???? * @jvms 5.3 Creation and Loading
 ????? *
 ????? * @since? 9
 ????? * @spec JPMS
@@ -2255,7 +2255,7 @@
 ????? *???????? this class loader; or an zero length array if no 
package has been
 ????? *???????? defined by this class loader.
 ????? *
-???? * @jvms 5.3 Run-time package
+???? * @jvms 5.3 Creation and Loading
 ????? *
 ????? * @since? 9
 ????? * @spec JPMS
--- old/src/java.base/share/classes/java/lang/Double.java 2019-05-19 
12:16:29.205761266 -0700
+++ new/src/java.base/share/classes/java/lang/Double.java 2019-05-19 
12:16:28.809761266 -0700
@@ -673,7 +673,7 @@
 ????? *
 ????? * @return? the {@code double} value represented by this object
 ????? *????????? converted to type {@code byte}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? * @since 1.1
 ????? */
 ???? public byte byteValue() {
@@ -686,7 +686,7 @@
 ????? *
 ????? * @return? the {@code double} value represented by this object
 ????? *????????? converted to type {@code short}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? * @since 1.1
 ????? */
 ???? public short shortValue() {
@@ -696,7 +696,7 @@
 ???? /**
 ????? * Returns the value of this {@code Double} as an {@code int}
 ????? * after a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? *
 ????? * @return? the {@code double} value represented by this object
 ????? *????????? converted to type {@code int}
@@ -711,7 +711,7 @@
 ????? *
 ????? * @return? the {@code double} value represented by this object
 ????? *????????? converted to type {@code long}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public long longValue() {
 ???????? return (long)value;
@@ -723,7 +723,7 @@
 ????? *
 ????? * @return? the {@code double} value represented by this object
 ????? *????????? converted to type {@code float}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? * @since 1.0
 ????? */
 ???? public float floatValue() {
--- old/src/java.base/share/classes/java/lang/Float.java 2019-05-19 
12:16:30.133761266 -0700
+++ new/src/java.base/share/classes/java/lang/Float.java 2019-05-19 
12:16:29.637761266 -0700
@@ -602,7 +602,7 @@
 ????? *
 ????? * @return? the {@code float} value represented by this object
 ????? *????????? converted to type {@code byte}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public byte byteValue() {
 ???????? return (byte)value;
@@ -614,7 +614,7 @@
 ????? *
 ????? * @return? the {@code float} value represented by this object
 ????? *????????? converted to type {@code short}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? * @since 1.1
 ????? */
 ???? public short shortValue() {
@@ -627,7 +627,7 @@
 ????? *
 ????? * @return? the {@code float} value represented by this object
 ????? *????????? converted to type {@code int}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public int intValue() {
 ???????? return (int)value;
@@ -639,7 +639,7 @@
 ????? *
 ????? * @return? the {@code float} value represented by this object
 ????? *????????? converted to type {@code long}
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public long longValue() {
 ???????? return (long)value;
@@ -661,7 +661,7 @@
 ????? *
 ????? * @return the {@code float} value represented by this
 ????? *???????? object converted to type {@code double}
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public double doubleValue() {
 ???????? return (double)value;
--- old/src/java.base/share/classes/java/lang/FunctionalInterface.java 
2019-05-19 12:16:31.105761266 -0700
+++ new/src/java.base/share/classes/java/lang/FunctionalInterface.java 
2019-05-19 12:16:30.609761266 -0700
@@ -57,7 +57,7 @@
 ? * regardless of whether or not a {@code FunctionalInterface}
 ? * annotation is present on the interface declaration.
 ? *
- * @jls 4.3.2. The Class Object
+ * @jls 4.3.2 The Class Object
 ? * @jls 9.8 Functional Interfaces
 ? * @jls 9.4.3 Interface Method Body
 ? * @jls 9.6.4.9 @FunctionalInterface
--- old/src/java.base/share/classes/java/lang/Integer.java 2019-05-19 
12:16:31.997761266 -0700
+++ new/src/java.base/share/classes/java/lang/Integer.java 2019-05-19 
12:16:31.529761266 -0700
@@ -1120,7 +1120,7 @@
 ???? /**
 ????? * Returns the value of this {@code Integer} as a {@code byte}
 ????? * after a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public byte byteValue() {
 ???????? return (byte)value;
@@ -1129,7 +1129,7 @@
 ???? /**
 ????? * Returns the value of this {@code Integer} as a {@code short}
 ????? * after a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public short shortValue() {
 ???????? return (short)value;
@@ -1147,7 +1147,7 @@
 ???? /**
 ????? * Returns the value of this {@code Integer} as a {@code long}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? * @see Integer#toUnsignedLong(int)
 ????? */
 ???? public long longValue() {
@@ -1157,7 +1157,7 @@
 ???? /**
 ????? * Returns the value of this {@code Integer} as a {@code float}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public float floatValue() {
 ???????? return (float)value;
@@ -1166,7 +1166,7 @@
 ???? /**
 ????? * Returns the value of this {@code Integer} as a {@code double}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public double doubleValue() {
 ???????? return (double)value;
--- old/src/java.base/share/classes/java/lang/Long.java 2019-05-19 
12:16:32.785761266 -0700
+++ new/src/java.base/share/classes/java/lang/Long.java 2019-05-19 
12:16:32.369761266 -0700
@@ -1339,7 +1339,7 @@
 ???? /**
 ????? * Returns the value of this {@code Long} as a {@code byte} after
 ????? * a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public byte byteValue() {
 ???????? return (byte)value;
@@ -1348,7 +1348,7 @@
 ???? /**
 ????? * Returns the value of this {@code Long} as a {@code short} after
 ????? * a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public short shortValue() {
 ???????? return (short)value;
@@ -1357,7 +1357,7 @@
 ???? /**
 ????? * Returns the value of this {@code Long} as an {@code int} after
 ????? * a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public int intValue() {
 ???????? return (int)value;
@@ -1375,7 +1375,7 @@
 ???? /**
 ????? * Returns the value of this {@code Long} as a {@code float} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public float floatValue() {
 ???????? return (float)value;
@@ -1384,7 +1384,7 @@
 ???? /**
 ????? * Returns the value of this {@code Long} as a {@code double}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public double doubleValue() {
 ???????? return (double)value;
--- old/src/java.base/share/classes/java/lang/Number.java 2019-05-19 
12:16:33.561761266 -0700
+++ new/src/java.base/share/classes/java/lang/Number.java 2019-05-19 
12:16:33.157761266 -0700
@@ -48,8 +48,8 @@
 ? *
 ? * @author????? Lee Boynton
 ? * @author????? Arthur van Hoff
- * @jls 5.1.2 Widening Primitive Conversions
- * @jls 5.1.3 Narrowing Primitive Conversions
+ * @jls 5.1.2 Widening Primitive Conversion
+ * @jls 5.1.3 Narrowing Primitive Conversion
 ? * @since?? 1.0
 ? */
 ?public abstract class Number implements java.io.Serializable {
--- old/src/java.base/share/classes/java/lang/Package.java 2019-05-19 
12:16:34.325761266 -0700
+++ new/src/java.base/share/classes/java/lang/Package.java 2019-05-19 
12:16:33.929761266 -0700
@@ -108,7 +108,7 @@
 ? * <em>named modules</em>.? Instead those packages are automatically 
defined
 ? * and have no specification and implementation versioning information.
 ? *
- * @jvms 5.3 Run-time package
+ * @jvms 5.3 Creation and Loading
 ? * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">
 ? * The JAR File Specification: Package Sealing</a>
 ? * @see ClassLoader#definePackage(String, String, String, String, 
String, String, String, URL)
--- old/src/java.base/share/classes/java/lang/Short.java 2019-05-19 
12:16:35.109761266 -0700
+++ new/src/java.base/share/classes/java/lang/Short.java 2019-05-19 
12:16:34.701761266 -0700
@@ -352,7 +352,7 @@
 ???? /**
 ????? * Returns the value of this {@code Short} as a {@code byte} after
 ????? * a narrowing primitive conversion.
-???? * @jls 5.1.3 Narrowing Primitive Conversions
+???? * @jls 5.1.3 Narrowing Primitive Conversion
 ????? */
 ???? public byte byteValue() {
 ???????? return (byte)value;
@@ -370,7 +370,7 @@
 ???? /**
 ????? * Returns the value of this {@code Short} as an {@code int} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public int intValue() {
 ???????? return (int)value;
@@ -379,7 +379,7 @@
 ???? /**
 ????? * Returns the value of this {@code Short} as a {@code long} after
 ????? * a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public long longValue() {
 ???????? return (long)value;
@@ -388,7 +388,7 @@
 ???? /**
 ????? * Returns the value of this {@code Short} as a {@code float}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public float floatValue() {
 ???????? return (float)value;
@@ -397,7 +397,7 @@
 ???? /**
 ????? * Returns the value of this {@code Short} as a {@code double}
 ????? * after a widening primitive conversion.
-???? * @jls 5.1.2 Widening Primitive Conversions
+???? * @jls 5.1.2 Widening Primitive Conversion
 ????? */
 ???? public double doubleValue() {
 ???????? return (double)value;
--- old/src/java.base/share/classes/java/lang/SuppressWarnings.java 
2019-05-19 12:16:35.933761266 -0700
+++ new/src/java.base/share/classes/java/lang/SuppressWarnings.java 
2019-05-19 12:16:35.485761266 -0700
@@ -49,7 +49,7 @@
 ? * @jls 4.8 Raw Types
 ? * @jls 4.12.2 Variables of Reference Type
 ? * @jls 5.1.9 Unchecked Conversion
- * @jls 5.5.2 Checked Casts and Unchecked Casts
+ * @jls 5.5 Casting Contexts
 ? * @jls 9.6.4.5 @SuppressWarnings
 ? */
 ?@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, 
MODULE})
--- old/src/java.base/share/classes/java/lang/constant/Constable.java 
2019-05-19 12:16:36.717761266 -0700
+++ new/src/java.base/share/classes/java/lang/constant/Constable.java 
2019-05-19 12:16:36.285761266 -0700
@@ -59,7 +59,7 @@
 ? * method handles, but not necessarily those produced by method handle
 ? * combinators.)
 ? * @jvms 4.4 The Constant Pool
- * @jvms 4.4.10 The CONSTANT_InvokeDynamic_info Structure
+ * @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code 
CONSTANT_InvokeDynamic_info} Structures
 ? *
 ? * @since 12
 ? */
--- old/src/java.base/share/classes/java/lang/reflect/Method.java 
2019-05-19 12:16:37.521761266 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Method.java 
2019-05-19 12:16:37.117761266 -0700
@@ -403,7 +403,7 @@
 ????? * @return a string describing this {@code Method}
 ????? *
 ????? * @jls 8.4.3 Method Modifiers
-???? * @jls 9.4?? Method Declarations
+???? * @jls 9.4 Method Declarations
 ????? * @jls 9.6.1 Annotation Type Elements
 ????? */
 ???? public String toString() {
@@ -474,7 +474,7 @@
 ????? * @since 1.5
 ????? *
 ????? * @jls 8.4.3 Method Modifiers
-???? * @jls 9.4?? Method Declarations
+???? * @jls 9.4 Method Declarations
 ????? * @jls 9.6.1 Annotation Type Elements
 ????? */
 ???? @Override
--- old/src/java.base/share/classes/java/lang/reflect/Modifier.java 
2019-05-19 12:16:38.353761266 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Modifier.java 
2019-05-19 12:16:37.917761266 -0700
@@ -394,7 +394,7 @@

 ???? /**
 ????? * The Java source modifiers that can be applied to a field.
-???? * @jls 8.3.1? Field Modifiers
+???? * @jls 8.3.1 Field Modifiers
 ????? */
 ???? private static final int FIELD_MODIFIERS =
 ???????? Modifier.PUBLIC???????? | Modifier.PROTECTED??? | 
Modifier.PRIVATE |
--- 
old/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
2019-05-19 12:16:39.161761266 -0700
+++ 
new/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
2019-05-19 12:16:38.757761266 -0700
@@ -114,7 +114,7 @@
 ? *
 ? * @since 1.8
 ? * @jls 9.6 Annotation Types
- * @jls 9.6.3.3 @Inherited
+ * @jls 9.6.4.3 {@code @Inherited}
 ? */
 ?public interface AnnotatedConstruct {
 ???? /**
--- 
old/src/java.compiler/share/classes/javax/lang/model/element/Element.java 
2019-05-19 12:16:40.001761266 -0700
+++ 
new/src/java.compiler/share/classes/javax/lang/model/element/Element.java 
2019-05-19 12:16:39.525761266 -0700
@@ -196,7 +196,7 @@
 ????? * @see ModuleElement#getEnclosedElements
 ????? * @see Elements#getAllMembers
 ????? * @jls 8.8.9 Default Constructor
-???? * @jls 8.9 Enums
+???? * @jls 8.9 Enum Types
 ????? * @revised 9
 ????? * @spec JPMS
 ????? */
--- 
old/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java 
2019-05-19 12:16:40.801761266 -0700
+++ 
new/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java 
2019-05-19 12:16:40.397761266 -0700
@@ -111,7 +111,7 @@
 ????? * More specifically, an <i>inner</i> type element is any nested 
type element that
 ????? * is not {@linkplain Modifier#STATIC static}.
 ????? * @return whether or not the constant is nested
-???? * @jls 14.3 Inner Classes and Enclosing Instances
+???? * @jls 14.3 Local Class Declarations
 ????? */
 ???? public boolean isNested() {
 ???????? return this != TOP_LEVEL;
--- old/src/java.compiler/share/classes/javax/lang/model/util/Types.java 
2019-05-19 12:16:41.557761266 -0700
+++ new/src/java.compiler/share/classes/javax/lang/model/util/Types.java 
2019-05-19 12:16:41.161761266 -0700
@@ -104,7 +104,7 @@
 ????? * @return {@code true} if and only if the first type is assignable
 ????? *????????? to the second
 ????? * @throws IllegalArgumentException if given a type for an 
executable, package, or module
-???? * @jls 5.2 Assignment Conversion
+???? * @jls 5.2 Assignment Contexts
 ????? */
 ???? boolean isAssignable(TypeMirror t1, TypeMirror t2);

@@ -115,7 +115,7 @@
 ????? * @param t2? the second type
 ????? * @return {@code true} if and only if the first type contains the 
second
 ????? * @throws IllegalArgumentException if given a type for an 
executable, package, or module
-???? * @jls 4.5.1.1 Type Argument Containment and Equivalence
+???? * @jls 4.5.1 Type Arguments of Parameterized Types
 ????? */
 ???? boolean contains(TypeMirror t1, TypeMirror t2);

--- 
old/src/jdk.compiler/share/classes/com/sun/source/tree/BinaryTree.java 
2019-05-19 12:16:42.329761266 -0700
+++ 
new/src/jdk.compiler/share/classes/com/sun/source/tree/BinaryTree.java 
2019-05-19 12:16:41.929761266 -0700
@@ -40,8 +40,8 @@
 ? * @jls 15.20 Relational Operators
 ? * @jls 15.21 Equality Operators
 ? * @jls 15.22 Bitwise and Logical Operators
- * @jls 15.23 Conditional-And Operator &&
- * @jls 15.24 Conditional-Or Operator ||
+ * @jls 15.23 Conditional-And Operator {@code &&}
+ * @jls 15.24 Conditional-Or Operator {@code ||}
 ? *
 ? * @author Peter von der Ah&eacute;
 ? * @author Jonathan Gibbons
--- 
old/src/jdk.compiler/share/classes/com/sun/source/tree/ModifiersTree.java 
2019-05-19 12:16:43.285761266 -0700
+++ 
new/src/jdk.compiler/share/classes/com/sun/source/tree/ModifiersTree.java 
2019-05-19 12:16:42.797761266 -0700
@@ -45,7 +45,7 @@
 ? * @jls 8.5.1 Static Member Type Declarations
 ? * @jls 8.8.3 Constructor Modifiers
 ? * @jls 9.1.1 Interface Modifiers
- * @jls 9.7?? Annotations
+ * @jls 9.7 Annotations
 ? *
 ? * @author Peter von der Ah&eacute;
 ? * @author Jonathan Gibbons
--- 
old/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Types.java 
2019-05-19 12:16:44.213761266 -0700
+++ 
new/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Types.java 
2019-05-19 12:16:43.721761266 -0700
@@ -2733,7 +2733,7 @@
 ????? * signature</em> of the other.? This is <b>not</b> an equivalence
 ????? * relation.
 ????? *
-???? * @jls section 8.4.2.
+???? * @jls 8.4.2 Method Signature
 ????? * @see #overrideEquivalent(Type t, Type s)
 ????? * @param t first signature (possibly raw).
 ????? * @param s second signature (could be subjected to erasure).
@@ -2752,7 +2752,7 @@
 ????? * equivalence</em>.? This is the natural extension of
 ????? * isSubSignature to an equivalence relation.
 ????? *
-???? * @jls section 8.4.2.
+???? * @jls 8.4.2 Method Signature
 ????? * @see #isSubSignature(Type t, Type s)
 ????? * @param t a signature (possible raw, could be subjected to
 ????? * erasure).
@@ -4214,7 +4214,7 @@

 ???? /**
 ????? * Return-Type-Substitutable.
-???? * @jls section 8.4.5
+???? * @jls 8.4.5 Method Result
 ????? */
 ???? public boolean returnTypeSubstitutable(Type r1, Type r2) {
 ???????? if (hasSameArgs(r1, r2))
--- 
old/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java 
2019-05-19 12:16:45.077761266 -0700
+++ 
new/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java 
2019-05-19 12:16:44.657761266 -0700
@@ -4222,7 +4222,7 @@
 ????????? * @param tree??? The tree making up the variable reference.
 ????????? * @param env???? The current environment.
 ????????? * @param v?????? The variable's symbol.
-???????? * @jls? section 8.9 Enums
+???????? * @jls 8.9 Enum Types
 ????????? */
 ???????? private void checkEnumInitializer(JCTree tree, 
Env<AttrContext> env, VarSymbol v) {
 ???????????? // JLS:
--- old/src/jdk.jshell/share/classes/jdk/jshell/ExpressionSnippet.java 
2019-05-19 12:16:45.941761266 -0700
+++ new/src/jdk.jshell/share/classes/jdk/jshell/ExpressionSnippet.java 
2019-05-19 12:16:45.505761266 -0700
@@ -36,7 +36,7 @@
 ? * and thus is thread-safe.
 ? *
 ? * @since 9
- * @jls 15: Expression.
+ * @jls 15 Expressions
 ? */
 ?public class ExpressionSnippet extends Snippet {

--- old/src/jdk.jshell/share/classes/jdk/jshell/ImportSnippet.java 
2019-05-19 12:16:47.045761266 -0700
+++ new/src/jdk.jshell/share/classes/jdk/jshell/ImportSnippet.java 
2019-05-19 12:16:46.629761266 -0700
@@ -36,7 +36,7 @@
 ? * and thus is thread-safe.
 ? *
 ? * @since 9
- * @jls 8.3: importDeclaration.
+ * @jls 7.5 Import Declarations
 ? */
 ?public class ImportSnippet extends PersistentSnippet {

--- old/src/jdk.jshell/share/classes/jdk/jshell/MethodSnippet.java 
2019-05-19 12:16:48.501761266 -0700
+++ new/src/jdk.jshell/share/classes/jdk/jshell/MethodSnippet.java 
2019-05-19 12:16:48.093761266 -0700
@@ -37,7 +37,7 @@
 ? * and thus is thread-safe.
 ? *
 ? * @since 9
- * @jls 8.4: MethodDeclaration.
+ * @jls 8.4 Method Declarations
 ? */
 ?public class MethodSnippet extends DeclarationSnippet {

--- old/src/jdk.jshell/share/classes/jdk/jshell/Snippet.java 2019-05-19 
12:16:49.593761266 -0700
+++ new/src/jdk.jshell/share/classes/jdk/jshell/Snippet.java 2019-05-19 
12:16:49.173761266 -0700
@@ -73,7 +73,7 @@
 ????????? * ({@link 
jdk.jshell.Snippet.SubKind#SINGLE_STATIC_IMPORT_SUBKIND}) --
 ????????? * use {@link jdk.jshell.Snippet#subKind()} to distinguish.
 ????????? *
-???????? * @jls 8.3: importDeclaration.
+???????? * @jls 7.5 Import Declarations
 ????????? * <P>
 ????????? * An import declaration is {@linkplain Kind#isPersistent() 
persistent}.
 ????????? */
@@ -91,7 +91,7 @@
 ????????? * annotation interfaces -- see {@link 
jdk.jshell.Snippet.SubKind} to
 ????????? * differentiate.
 ????????? *
-???????? * @jls 7.6: TypeDeclaration.
+???????? * @jls 7.6 Top Level Type Declarations
 ????????? * <P>
 ????????? * A type declaration is {@linkplain Kind#isPersistent() 
persistent}.
 ????????? */
@@ -101,7 +101,7 @@
 ????????? * A method declaration.
 ????????? * The snippet is an instance of {@link jdk.jshell.MethodSnippet}.
 ????????? *
-???????? * @jls 8.4: MethodDeclaration.
+???????? * @jls 8.4 Method Declarations
 ????????? * <P>
 ????????? * A method declaration is {@linkplain Kind#isPersistent() 
persistent}.
 ????????? */
@@ -116,7 +116,7 @@
 ????????? * variable representing an expression -- see
 ????????? * {@link jdk.jshell.Snippet.SubKind}to differentiate.
 ????????? *
-???????? * @jls 8.3: FieldDeclaration.
+???????? * @jls 8.3 Field Declarations
 ????????? * <P>
 ????????? * A variable declaration is {@linkplain Kind#isPersistent() 
persistent}.
 ????????? */
@@ -133,7 +133,7 @@
 ????????? * All other expression forms (operators, method calls, ...) 
generate a
 ????????? * scratch variable and so are instead of the VAR Kind.
 ????????? *
-???????? * @jls 15: Expression.
+???????? * @jls 15 Expressions
 ????????? */
 ???????? EXPRESSION(false),

@@ -141,7 +141,7 @@
 ????????? * A statement.
 ????????? * The snippet is an instance of {@link 
jdk.jshell.StatementSnippet}.
 ????????? *
-???????? * @jls 14.5: Statement.
+???????? * @jls 14.5 Statements
 ????????? */
 ???????? STATEMENT(false),

@@ -185,99 +185,97 @@
 ???????? /**
 ????????? * Single-Type-Import Declaration.
 ????????? * An import declaration of a single type.
-???????? * @jls 7.5.1 SingleTypeImportDeclaration.
+???????? * @jls 7.5.1 Single-Type-Import Declarations
 ????????? */
 ???????? SINGLE_TYPE_IMPORT_SUBKIND(Kind.IMPORT),

 ???????? /**
 ????????? * Type-Import-on-Demand Declaration.
 ????????? * A non-static "star" import.
-???????? * @jls 7.5.2. TypeImportOnDemandDeclaration.
+???????? * @jls 7.5.2 Type-Import-on-Demand Declarations
 ????????? */
 ???????? TYPE_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),

 ???????? /**
 ????????? * Single-Static-Import Declaration.
 ????????? * An import of a static member.
-???????? * @jls 7.5.3 Single-Static-Import.
+???????? * @jls 7.5.3 Single-Static-Import Declarations
 ????????? */
 ???????? SINGLE_STATIC_IMPORT_SUBKIND(Kind.IMPORT),

 ???????? /**
 ????????? * Static-Import-on-Demand Declaration.
 ????????? * A static "star" import of all static members of a named type.
-???????? * @jls 7.5.4. Static-Import-on-Demand Static "star" import.
+???????? * @jls 7.5.4 Static-Import-on-Demand Declarations
 ????????? */
 ???????? STATIC_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),

 ???????? /**
 ????????? * A class declaration.
 ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
-???????? * @jls 8.1. NormalClassDeclaration.
+???????? * @jls 8.1 Class Declarations
 ????????? */
 ???????? CLASS_SUBKIND(Kind.TYPE_DECL),

 ???????? /**
 ????????? * An interface declaration.
 ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
-???????? * @jls 9.1. NormalInterfaceDeclaration.
+???????? * @jls 9.1 Interface Declarations
 ????????? */
 ???????? INTERFACE_SUBKIND(Kind.TYPE_DECL),

 ???????? /**
 ????????? * An enum declaration.
 ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
-???????? * @jls 8.9. EnumDeclaration.
+???????? * @jls 8.9 Enum Types
 ????????? */
 ???????? ENUM_SUBKIND(Kind.TYPE_DECL),

 ???????? /**
 ????????? * An annotation interface declaration. A {@code SubKind} of
 ????????? * {@link Kind#TYPE_DECL}.
-???????? * @jls 9.6. AnnotationTypeDeclaration.
+???????? * @jls 9.6 Annotation Types
 ????????? */
 ???????? ANNOTATION_TYPE_SUBKIND(Kind.TYPE_DECL),

 ???????? /**
 ????????? * A method. The only {@code SubKind} for {@link Kind#METHOD}.
-???????? * @jls 8.4. MethodDeclaration.
+???????? * @jls 8.4 Method Declarations
 ????????? */
 ???????? METHOD_SUBKIND(Kind.METHOD),

 ???????? /**
 ????????? * A variable declaration without initializer.
 ????????? * A {@code SubKind} of {@link Kind#VAR}.
-???????? * @jls 8.3. VariableDeclarator without VariableInitializer in
-???????? * FieldDeclaration.
+???????? * @jls 8.3 Field Declarations
 ????????? */
 ???????? VAR_DECLARATION_SUBKIND(Kind.VAR, true, true),

 ???????? /**
 ????????? * A variable declaration with an initializer expression. A
 ????????? * {@code SubKind} of {@link Kind#VAR}.
-???????? * @jls 8.3. VariableDeclarator with VariableInitializer in
-???????? * FieldDeclaration.
+???????? * @jls 8.3 Field Declarations
 ????????? */
 ???????? VAR_DECLARATION_WITH_INITIALIZER_SUBKIND(Kind.VAR, true, true),

 ???????? /**
 ????????? * An expression whose value has been stored in a temporary 
variable. A
 ????????? * {@code SubKind} of {@link Kind#VAR}.
-???????? * @jls 15. Primary.
+???????? * @jls 15 Expressions
 ????????? */
 ???????? TEMP_VAR_EXPRESSION_SUBKIND(Kind.VAR, true, true),

 ???????? /**
 ????????? * A simple variable reference expression. A {@code SubKind} of
 ????????? * {@link Kind#EXPRESSION}.
-???????? * @jls 15.11. Field Access as 3.8. Identifier.
+???????? * @jls 15.11 Field Access Expressions
 ????????? */
 ???????? VAR_VALUE_SUBKIND(Kind.EXPRESSION, true, true),

 ???????? /**
 ????????? * An assignment expression. A {@code SubKind} of
 ????????? * {@link Kind#EXPRESSION}.
-???????? * @jls 15.26. Assignment.
+???????? * @jls 15.26 Assignment Operators
 ????????? */
 ???????? ASSIGNMENT_SUBKIND(Kind.EXPRESSION, true, true),

@@ -289,7 +287,7 @@

 ???????? /**
 ????????? * A statement. The only {@code SubKind} for {@link 
Kind#STATEMENT}.
-???????? * @jls 14.5. Statement.
+???????? * @jls 14.5 Statements
 ????????? */
 ???????? STATEMENT_SUBKIND(Kind.STATEMENT, true, false),

--- old/src/jdk.jshell/share/classes/jdk/jshell/StatementSnippet.java 
2019-05-19 12:16:50.421761266 -0700
+++ new/src/jdk.jshell/share/classes/jdk/jshell/StatementSnippet.java 
2019-05-19 12:16:49.985761266 -0700
@@ -36,7 +36,7 @@
 ? * and thus is thread-safe.
 ? *
 ? * @since 9
- * @jls 14.5: Statement.
+ * @jls 14.5 Statements
 ? */
 ?public class StatementSnippet extends Snippet {

--- old/src/jdk.jshell/share/classes/jdk/jshell/VarSnippet.java 
2019-05-19 12:16:51.549761266 -0700
+++ new/src/jdk.jshell/share/classes/jdk/jshell/VarSnippet.java 
2019-05-19 12:16:51.117761266 -0700
@@ -39,7 +39,7 @@
 ? * and thus is thread-safe.
 ? *
 ? * @since 9
- * @jls 8.3: FieldDeclaration.
+ * @jls 8.3 Field Declarations
 ? */
 ?public class VarSnippet extends DeclarationSnippet {



From TOSHIONA at jp.ibm.com  Mon May 20 08:12:38 2019
From: TOSHIONA at jp.ibm.com (Toshio 5 Nakamura)
Date: Mon, 20 May 2019 17:12:38 +0900
Subject: RFR: 8224184: jshell got IOException at exiting with AIX
Message-ID: <OF6FAA0433.E1E08D96-ON00258400.002C5B08-49258400.002D1A74@notes.na.collabserv.com>


Hi,

Could you review JDK-8224184: jshell got IOException at exiting with AIX?
Also, I'd like to have a sponsor of the patch (I'm an author).

Issue: https://bugs.openjdk.java.net/browse/JDK-8224184
Webrev: http://cr.openjdk.java.net/~tnakamura/8224184/webrev.00

AIX doesn't show "min" or "time" by "stty -a" when "icanon" is defined.
This caused invalid value was trying to be set, and IOException was thrown.

Thanks,
Toshio Nakamura

From jonathan.gibbons at oracle.com  Mon May 20 18:03:24 2019
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Mon, 20 May 2019 11:03:24 -0700
Subject: JDK 13 RFR of JDK-8224175: Fix inconsistencies in @jls and @jvms
 tags
In-Reply-To: <478b540e-35a0-b9df-8bf3-c03b0422af8f@oracle.com>
References: <478b540e-35a0-b9df-8bf3-c03b0422af8f@oracle.com>
Message-ID: <0d8a4182-49c4-154d-ab66-6dbb47bf8c69@oracle.com>

Looks good to me.

-- Jon


On 05/19/2019 12:36 PM, Joe Darcy wrote:
> Hello,
>
> Thanks to some tooling developed by Jon Gibbons, inconsistencies in 
> the section names and numbers in the @jls and @jvms javadoc tags in 
> the jdk and the names and numbers of the current specifications have 
> been identified. These inconsistencies should be fixed.
>
> The names and numbers of the section titles in JLS and JVMS are 
> *mostly* stable, but a few sections have changed most notably for the 
> usage of @jls tags:
>
> ??? * 8.9 "Enum" -> "Enum Type" in Java SE 8
> ??? * 5.1.2 "Widening Primitive Conversions" -> "Widening Primitive 
> *Conversion*" in Java SE 7
>
> Two uses of "@jvms 5.3 Run-time package" refer to the term "Run-time 
> package" defined in that section. The term was replaced by the section 
> name in both cases.
>
> In java.lang.SuppressWarnings, a reference to the section "5.5.2 
> Checked Casts and Unchecked Casts", which was removed in Java SE 9, 
> was replaced with a reference to the enclosing section "5.5. Casting 
> Contexts".
>
> The usage of @jls in jshell was less consistent and has been regularized.
>
> Full webrev at:
>
> ??? http://cr.openjdk.java.net/~darcy/8224175.0/
>
> Patch below.
>
> Thanks,
>
> -Joe
>
> --- old/src/java.base/share/classes/java/lang/Byte.java 2019-05-19 
> 12:16:26.705761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Byte.java 2019-05-19 
> 12:16:26.137761266 -0700
> @@ -356,7 +356,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code short} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public short shortValue() {
> ???????? return (short)value;
> @@ -365,7 +365,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as an {@code int} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -374,7 +374,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code long} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -383,7 +383,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code float} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -392,7 +392,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/Class.java 2019-05-19 
> 12:16:27.597761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Class.java 2019-05-19 
> 12:16:27.161761266 -0700
> @@ -999,7 +999,7 @@
> ????? *
> ????? * @since 9
> ????? * @spec JPMS
> -???? * @jls 6.7? Fully Qualified Names
> +???? * @jls 6.7 Fully Qualified Names
> ????? */
> ???? public String getPackageName() {
> ???????? String pn = this.packageName;
> @@ -3910,7 +3910,8 @@
> ????? *???????? SecurityManager#checkPackageAccess 
> s.checkPackageAccess()}
> ????? *???????? denies access to the package of the returned class
> ????? * @since 11
> -???? * @jvms 4.7.28 and 4.7.29 NestHost and NestMembers attributes
> +???? * @jvms 4.7.28 The {@code NestHost} Attribute
> +???? * @jvms 4.7.29 The {@code NestMembers} Attribute
> ????? * @jvms 5.4.4 Access Control
> ????? */
> ???? @CallerSensitive
> --- old/src/java.base/share/classes/java/lang/ClassLoader.java 
> 2019-05-19 12:16:28.429761266 -0700
> +++ new/src/java.base/share/classes/java/lang/ClassLoader.java 
> 2019-05-19 12:16:28.041761266 -0700
> @@ -222,7 +222,7 @@
> ? * or a fully qualified name as defined by
> ? * <cite>The Java&trade; Language Specification</cite>.
> ? *
> - * @jls 6.7? Fully Qualified Names
> + * @jls 6.7 Fully Qualified Names
> ? * @jls 13.1 The Form of a Binary
> ? * @see????? #resolveClass(Class)
> ? * @since 1.0
> @@ -2194,7 +2194,7 @@
> ????? * @revised 9
> ????? * @spec JPMS
> ????? *
> -???? * @jvms 5.3 Run-time package
> +???? * @jvms 5.3 Creation and Loading
> ????? * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">
> ????? *????? The JAR File Specification: Package Sealing</a>
> ????? */
> @@ -2228,7 +2228,7 @@
> ????? * @throws? NullPointerException
> ????? *????????? if {@code name} is {@code null}.
> ????? *
> -???? * @jvms 5.3 Run-time package
> +???? * @jvms 5.3 Creation and Loading
> ????? *
> ????? * @since? 9
> ????? * @spec JPMS
> @@ -2255,7 +2255,7 @@
> ????? *???????? this class loader; or an zero length array if no 
> package has been
> ????? *???????? defined by this class loader.
> ????? *
> -???? * @jvms 5.3 Run-time package
> +???? * @jvms 5.3 Creation and Loading
> ????? *
> ????? * @since? 9
> ????? * @spec JPMS
> --- old/src/java.base/share/classes/java/lang/Double.java 2019-05-19 
> 12:16:29.205761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Double.java 2019-05-19 
> 12:16:28.809761266 -0700
> @@ -673,7 +673,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code byte}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.1
> ????? */
> ???? public byte byteValue() {
> @@ -686,7 +686,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code short}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.1
> ????? */
> ???? public short shortValue() {
> @@ -696,7 +696,7 @@
> ???? /**
> ????? * Returns the value of this {@code Double} as an {@code int}
> ????? * after a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code int}
> @@ -711,7 +711,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code long}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -723,7 +723,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code float}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.0
> ????? */
> ???? public float floatValue() {
> --- old/src/java.base/share/classes/java/lang/Float.java 2019-05-19 
> 12:16:30.133761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Float.java 2019-05-19 
> 12:16:29.637761266 -0700
> @@ -602,7 +602,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code byte}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -614,7 +614,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code short}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.1
> ????? */
> ???? public short shortValue() {
> @@ -627,7 +627,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code int}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -639,7 +639,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code long}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -661,7 +661,7 @@
> ????? *
> ????? * @return the {@code float} value represented by this
> ????? *???????? object converted to type {@code double}
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/FunctionalInterface.java 
> 2019-05-19 12:16:31.105761266 -0700
> +++ new/src/java.base/share/classes/java/lang/FunctionalInterface.java 
> 2019-05-19 12:16:30.609761266 -0700
> @@ -57,7 +57,7 @@
> ? * regardless of whether or not a {@code FunctionalInterface}
> ? * annotation is present on the interface declaration.
> ? *
> - * @jls 4.3.2. The Class Object
> + * @jls 4.3.2 The Class Object
> ? * @jls 9.8 Functional Interfaces
> ? * @jls 9.4.3 Interface Method Body
> ? * @jls 9.6.4.9 @FunctionalInterface
> --- old/src/java.base/share/classes/java/lang/Integer.java 2019-05-19 
> 12:16:31.997761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Integer.java 2019-05-19 
> 12:16:31.529761266 -0700
> @@ -1120,7 +1120,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code byte}
> ????? * after a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -1129,7 +1129,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code short}
> ????? * after a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public short shortValue() {
> ???????? return (short)value;
> @@ -1147,7 +1147,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code long}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? * @see Integer#toUnsignedLong(int)
> ????? */
> ???? public long longValue() {
> @@ -1157,7 +1157,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code float}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -1166,7 +1166,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/Long.java 2019-05-19 
> 12:16:32.785761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Long.java 2019-05-19 
> 12:16:32.369761266 -0700
> @@ -1339,7 +1339,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code byte} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -1348,7 +1348,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code short} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public short shortValue() {
> ???????? return (short)value;
> @@ -1357,7 +1357,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as an {@code int} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -1375,7 +1375,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code float} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -1384,7 +1384,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/Number.java 2019-05-19 
> 12:16:33.561761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Number.java 2019-05-19 
> 12:16:33.157761266 -0700
> @@ -48,8 +48,8 @@
> ? *
> ? * @author????? Lee Boynton
> ? * @author????? Arthur van Hoff
> - * @jls 5.1.2 Widening Primitive Conversions
> - * @jls 5.1.3 Narrowing Primitive Conversions
> + * @jls 5.1.2 Widening Primitive Conversion
> + * @jls 5.1.3 Narrowing Primitive Conversion
> ? * @since?? 1.0
> ? */
> ?public abstract class Number implements java.io.Serializable {
> --- old/src/java.base/share/classes/java/lang/Package.java 2019-05-19 
> 12:16:34.325761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Package.java 2019-05-19 
> 12:16:33.929761266 -0700
> @@ -108,7 +108,7 @@
> ? * <em>named modules</em>.? Instead those packages are automatically 
> defined
> ? * and have no specification and implementation versioning information.
> ? *
> - * @jvms 5.3 Run-time package
> + * @jvms 5.3 Creation and Loading
> ? * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">
> ? * The JAR File Specification: Package Sealing</a>
> ? * @see ClassLoader#definePackage(String, String, String, String, 
> String, String, String, URL)
> --- old/src/java.base/share/classes/java/lang/Short.java 2019-05-19 
> 12:16:35.109761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Short.java 2019-05-19 
> 12:16:34.701761266 -0700
> @@ -352,7 +352,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code byte} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -370,7 +370,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as an {@code int} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -379,7 +379,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code long} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -388,7 +388,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code float}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -397,7 +397,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/SuppressWarnings.java 
> 2019-05-19 12:16:35.933761266 -0700
> +++ new/src/java.base/share/classes/java/lang/SuppressWarnings.java 
> 2019-05-19 12:16:35.485761266 -0700
> @@ -49,7 +49,7 @@
> ? * @jls 4.8 Raw Types
> ? * @jls 4.12.2 Variables of Reference Type
> ? * @jls 5.1.9 Unchecked Conversion
> - * @jls 5.5.2 Checked Casts and Unchecked Casts
> + * @jls 5.5 Casting Contexts
> ? * @jls 9.6.4.5 @SuppressWarnings
> ? */
> ?@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, 
> MODULE})
> --- old/src/java.base/share/classes/java/lang/constant/Constable.java 
> 2019-05-19 12:16:36.717761266 -0700
> +++ new/src/java.base/share/classes/java/lang/constant/Constable.java 
> 2019-05-19 12:16:36.285761266 -0700
> @@ -59,7 +59,7 @@
> ? * method handles, but not necessarily those produced by method handle
> ? * combinators.)
> ? * @jvms 4.4 The Constant Pool
> - * @jvms 4.4.10 The CONSTANT_InvokeDynamic_info Structure
> + * @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code 
> CONSTANT_InvokeDynamic_info} Structures
> ? *
> ? * @since 12
> ? */
> --- old/src/java.base/share/classes/java/lang/reflect/Method.java 
> 2019-05-19 12:16:37.521761266 -0700
> +++ new/src/java.base/share/classes/java/lang/reflect/Method.java 
> 2019-05-19 12:16:37.117761266 -0700
> @@ -403,7 +403,7 @@
> ????? * @return a string describing this {@code Method}
> ????? *
> ????? * @jls 8.4.3 Method Modifiers
> -???? * @jls 9.4?? Method Declarations
> +???? * @jls 9.4 Method Declarations
> ????? * @jls 9.6.1 Annotation Type Elements
> ????? */
> ???? public String toString() {
> @@ -474,7 +474,7 @@
> ????? * @since 1.5
> ????? *
> ????? * @jls 8.4.3 Method Modifiers
> -???? * @jls 9.4?? Method Declarations
> +???? * @jls 9.4 Method Declarations
> ????? * @jls 9.6.1 Annotation Type Elements
> ????? */
> ???? @Override
> --- old/src/java.base/share/classes/java/lang/reflect/Modifier.java 
> 2019-05-19 12:16:38.353761266 -0700
> +++ new/src/java.base/share/classes/java/lang/reflect/Modifier.java 
> 2019-05-19 12:16:37.917761266 -0700
> @@ -394,7 +394,7 @@
>
> ???? /**
> ????? * The Java source modifiers that can be applied to a field.
> -???? * @jls 8.3.1? Field Modifiers
> +???? * @jls 8.3.1 Field Modifiers
> ????? */
> ???? private static final int FIELD_MODIFIERS =
> ???????? Modifier.PUBLIC???????? | Modifier.PROTECTED??? | 
> Modifier.PRIVATE |
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
> 2019-05-19 12:16:39.161761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
> 2019-05-19 12:16:38.757761266 -0700
> @@ -114,7 +114,7 @@
> ? *
> ? * @since 1.8
> ? * @jls 9.6 Annotation Types
> - * @jls 9.6.3.3 @Inherited
> + * @jls 9.6.4.3 {@code @Inherited}
> ? */
> ?public interface AnnotatedConstruct {
> ???? /**
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/element/Element.java 
> 2019-05-19 12:16:40.001761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/element/Element.java 
> 2019-05-19 12:16:39.525761266 -0700
> @@ -196,7 +196,7 @@
> ????? * @see ModuleElement#getEnclosedElements
> ????? * @see Elements#getAllMembers
> ????? * @jls 8.8.9 Default Constructor
> -???? * @jls 8.9 Enums
> +???? * @jls 8.9 Enum Types
> ????? * @revised 9
> ????? * @spec JPMS
> ????? */
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java 
> 2019-05-19 12:16:40.801761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java 
> 2019-05-19 12:16:40.397761266 -0700
> @@ -111,7 +111,7 @@
> ????? * More specifically, an <i>inner</i> type element is any nested 
> type element that
> ????? * is not {@linkplain Modifier#STATIC static}.
> ????? * @return whether or not the constant is nested
> -???? * @jls 14.3 Inner Classes and Enclosing Instances
> +???? * @jls 14.3 Local Class Declarations
> ????? */
> ???? public boolean isNested() {
> ???????? return this != TOP_LEVEL;
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/util/Types.java 
> 2019-05-19 12:16:41.557761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/util/Types.java 
> 2019-05-19 12:16:41.161761266 -0700
> @@ -104,7 +104,7 @@
> ????? * @return {@code true} if and only if the first type is assignable
> ????? *????????? to the second
> ????? * @throws IllegalArgumentException if given a type for an 
> executable, package, or module
> -???? * @jls 5.2 Assignment Conversion
> +???? * @jls 5.2 Assignment Contexts
> ????? */
> ???? boolean isAssignable(TypeMirror t1, TypeMirror t2);
>
> @@ -115,7 +115,7 @@
> ????? * @param t2? the second type
> ????? * @return {@code true} if and only if the first type contains 
> the second
> ????? * @throws IllegalArgumentException if given a type for an 
> executable, package, or module
> -???? * @jls 4.5.1.1 Type Argument Containment and Equivalence
> +???? * @jls 4.5.1 Type Arguments of Parameterized Types
> ????? */
> ???? boolean contains(TypeMirror t1, TypeMirror t2);
>
> --- 
> old/src/jdk.compiler/share/classes/com/sun/source/tree/BinaryTree.java 
> 2019-05-19 12:16:42.329761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/source/tree/BinaryTree.java 
> 2019-05-19 12:16:41.929761266 -0700
> @@ -40,8 +40,8 @@
> ? * @jls 15.20 Relational Operators
> ? * @jls 15.21 Equality Operators
> ? * @jls 15.22 Bitwise and Logical Operators
> - * @jls 15.23 Conditional-And Operator &&
> - * @jls 15.24 Conditional-Or Operator ||
> + * @jls 15.23 Conditional-And Operator {@code &&}
> + * @jls 15.24 Conditional-Or Operator {@code ||}
> ? *
> ? * @author Peter von der Ah&eacute;
> ? * @author Jonathan Gibbons
> --- 
> old/src/jdk.compiler/share/classes/com/sun/source/tree/ModifiersTree.java 
> 2019-05-19 12:16:43.285761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/source/tree/ModifiersTree.java 
> 2019-05-19 12:16:42.797761266 -0700
> @@ -45,7 +45,7 @@
> ? * @jls 8.5.1 Static Member Type Declarations
> ? * @jls 8.8.3 Constructor Modifiers
> ? * @jls 9.1.1 Interface Modifiers
> - * @jls 9.7?? Annotations
> + * @jls 9.7 Annotations
> ? *
> ? * @author Peter von der Ah&eacute;
> ? * @author Jonathan Gibbons
> --- 
> old/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Types.java 
> 2019-05-19 12:16:44.213761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Types.java 
> 2019-05-19 12:16:43.721761266 -0700
> @@ -2733,7 +2733,7 @@
> ????? * signature</em> of the other.? This is <b>not</b> an equivalence
> ????? * relation.
> ????? *
> -???? * @jls section 8.4.2.
> +???? * @jls 8.4.2 Method Signature
> ????? * @see #overrideEquivalent(Type t, Type s)
> ????? * @param t first signature (possibly raw).
> ????? * @param s second signature (could be subjected to erasure).
> @@ -2752,7 +2752,7 @@
> ????? * equivalence</em>.? This is the natural extension of
> ????? * isSubSignature to an equivalence relation.
> ????? *
> -???? * @jls section 8.4.2.
> +???? * @jls 8.4.2 Method Signature
> ????? * @see #isSubSignature(Type t, Type s)
> ????? * @param t a signature (possible raw, could be subjected to
> ????? * erasure).
> @@ -4214,7 +4214,7 @@
>
> ???? /**
> ????? * Return-Type-Substitutable.
> -???? * @jls section 8.4.5
> +???? * @jls 8.4.5 Method Result
> ????? */
> ???? public boolean returnTypeSubstitutable(Type r1, Type r2) {
> ???????? if (hasSameArgs(r1, r2))
> --- 
> old/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java 
> 2019-05-19 12:16:45.077761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java 
> 2019-05-19 12:16:44.657761266 -0700
> @@ -4222,7 +4222,7 @@
> ????????? * @param tree??? The tree making up the variable reference.
> ????????? * @param env???? The current environment.
> ????????? * @param v?????? The variable's symbol.
> -???????? * @jls? section 8.9 Enums
> +???????? * @jls 8.9 Enum Types
> ????????? */
> ???????? private void checkEnumInitializer(JCTree tree, 
> Env<AttrContext> env, VarSymbol v) {
> ???????????? // JLS:
> --- old/src/jdk.jshell/share/classes/jdk/jshell/ExpressionSnippet.java 
> 2019-05-19 12:16:45.941761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/ExpressionSnippet.java 
> 2019-05-19 12:16:45.505761266 -0700
> @@ -36,7 +36,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 15: Expression.
> + * @jls 15 Expressions
> ? */
> ?public class ExpressionSnippet extends Snippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/ImportSnippet.java 
> 2019-05-19 12:16:47.045761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/ImportSnippet.java 
> 2019-05-19 12:16:46.629761266 -0700
> @@ -36,7 +36,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 8.3: importDeclaration.
> + * @jls 7.5 Import Declarations
> ? */
> ?public class ImportSnippet extends PersistentSnippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/MethodSnippet.java 
> 2019-05-19 12:16:48.501761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/MethodSnippet.java 
> 2019-05-19 12:16:48.093761266 -0700
> @@ -37,7 +37,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 8.4: MethodDeclaration.
> + * @jls 8.4 Method Declarations
> ? */
> ?public class MethodSnippet extends DeclarationSnippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/Snippet.java 
> 2019-05-19 12:16:49.593761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/Snippet.java 
> 2019-05-19 12:16:49.173761266 -0700
> @@ -73,7 +73,7 @@
> ????????? * ({@link 
> jdk.jshell.Snippet.SubKind#SINGLE_STATIC_IMPORT_SUBKIND}) --
> ????????? * use {@link jdk.jshell.Snippet#subKind()} to distinguish.
> ????????? *
> -???????? * @jls 8.3: importDeclaration.
> +???????? * @jls 7.5 Import Declarations
> ????????? * <P>
> ????????? * An import declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -91,7 +91,7 @@
> ????????? * annotation interfaces -- see {@link 
> jdk.jshell.Snippet.SubKind} to
> ????????? * differentiate.
> ????????? *
> -???????? * @jls 7.6: TypeDeclaration.
> +???????? * @jls 7.6 Top Level Type Declarations
> ????????? * <P>
> ????????? * A type declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -101,7 +101,7 @@
> ????????? * A method declaration.
> ????????? * The snippet is an instance of {@link 
> jdk.jshell.MethodSnippet}.
> ????????? *
> -???????? * @jls 8.4: MethodDeclaration.
> +???????? * @jls 8.4 Method Declarations
> ????????? * <P>
> ????????? * A method declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -116,7 +116,7 @@
> ????????? * variable representing an expression -- see
> ????????? * {@link jdk.jshell.Snippet.SubKind}to differentiate.
> ????????? *
> -???????? * @jls 8.3: FieldDeclaration.
> +???????? * @jls 8.3 Field Declarations
> ????????? * <P>
> ????????? * A variable declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -133,7 +133,7 @@
> ????????? * All other expression forms (operators, method calls, ...) 
> generate a
> ????????? * scratch variable and so are instead of the VAR Kind.
> ????????? *
> -???????? * @jls 15: Expression.
> +???????? * @jls 15 Expressions
> ????????? */
> ???????? EXPRESSION(false),
>
> @@ -141,7 +141,7 @@
> ????????? * A statement.
> ????????? * The snippet is an instance of {@link 
> jdk.jshell.StatementSnippet}.
> ????????? *
> -???????? * @jls 14.5: Statement.
> +???????? * @jls 14.5 Statements
> ????????? */
> ???????? STATEMENT(false),
>
> @@ -185,99 +185,97 @@
> ???????? /**
> ????????? * Single-Type-Import Declaration.
> ????????? * An import declaration of a single type.
> -???????? * @jls 7.5.1 SingleTypeImportDeclaration.
> +???????? * @jls 7.5.1 Single-Type-Import Declarations
> ????????? */
> ???????? SINGLE_TYPE_IMPORT_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * Type-Import-on-Demand Declaration.
> ????????? * A non-static "star" import.
> -???????? * @jls 7.5.2. TypeImportOnDemandDeclaration.
> +???????? * @jls 7.5.2 Type-Import-on-Demand Declarations
> ????????? */
> ???????? TYPE_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * Single-Static-Import Declaration.
> ????????? * An import of a static member.
> -???????? * @jls 7.5.3 Single-Static-Import.
> +???????? * @jls 7.5.3 Single-Static-Import Declarations
> ????????? */
> ???????? SINGLE_STATIC_IMPORT_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * Static-Import-on-Demand Declaration.
> ????????? * A static "star" import of all static members of a named type.
> -???????? * @jls 7.5.4. Static-Import-on-Demand Static "star" import.
> +???????? * @jls 7.5.4 Static-Import-on-Demand Declarations
> ????????? */
> ???????? STATIC_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * A class declaration.
> ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
> -???????? * @jls 8.1. NormalClassDeclaration.
> +???????? * @jls 8.1 Class Declarations
> ????????? */
> ???????? CLASS_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * An interface declaration.
> ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
> -???????? * @jls 9.1. NormalInterfaceDeclaration.
> +???????? * @jls 9.1 Interface Declarations
> ????????? */
> ???????? INTERFACE_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * An enum declaration.
> ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
> -???????? * @jls 8.9. EnumDeclaration.
> +???????? * @jls 8.9 Enum Types
> ????????? */
> ???????? ENUM_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * An annotation interface declaration. A {@code SubKind} of
> ????????? * {@link Kind#TYPE_DECL}.
> -???????? * @jls 9.6. AnnotationTypeDeclaration.
> +???????? * @jls 9.6 Annotation Types
> ????????? */
> ???????? ANNOTATION_TYPE_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * A method. The only {@code SubKind} for {@link Kind#METHOD}.
> -???????? * @jls 8.4. MethodDeclaration.
> +???????? * @jls 8.4 Method Declarations
> ????????? */
> ???????? METHOD_SUBKIND(Kind.METHOD),
>
> ???????? /**
> ????????? * A variable declaration without initializer.
> ????????? * A {@code SubKind} of {@link Kind#VAR}.
> -???????? * @jls 8.3. VariableDeclarator without VariableInitializer in
> -???????? * FieldDeclaration.
> +???????? * @jls 8.3 Field Declarations
> ????????? */
> ???????? VAR_DECLARATION_SUBKIND(Kind.VAR, true, true),
>
> ???????? /**
> ????????? * A variable declaration with an initializer expression. A
> ????????? * {@code SubKind} of {@link Kind#VAR}.
> -???????? * @jls 8.3. VariableDeclarator with VariableInitializer in
> -???????? * FieldDeclaration.
> +???????? * @jls 8.3 Field Declarations
> ????????? */
> ???????? VAR_DECLARATION_WITH_INITIALIZER_SUBKIND(Kind.VAR, true, true),
>
> ???????? /**
> ????????? * An expression whose value has been stored in a temporary 
> variable. A
> ????????? * {@code SubKind} of {@link Kind#VAR}.
> -???????? * @jls 15. Primary.
> +???????? * @jls 15 Expressions
> ????????? */
> ???????? TEMP_VAR_EXPRESSION_SUBKIND(Kind.VAR, true, true),
>
> ???????? /**
> ????????? * A simple variable reference expression. A {@code SubKind} of
> ????????? * {@link Kind#EXPRESSION}.
> -???????? * @jls 15.11. Field Access as 3.8. Identifier.
> +???????? * @jls 15.11 Field Access Expressions
> ????????? */
> ???????? VAR_VALUE_SUBKIND(Kind.EXPRESSION, true, true),
>
> ???????? /**
> ????????? * An assignment expression. A {@code SubKind} of
> ????????? * {@link Kind#EXPRESSION}.
> -???????? * @jls 15.26. Assignment.
> +???????? * @jls 15.26 Assignment Operators
> ????????? */
> ???????? ASSIGNMENT_SUBKIND(Kind.EXPRESSION, true, true),
>
> @@ -289,7 +287,7 @@
>
> ???????? /**
> ????????? * A statement. The only {@code SubKind} for {@link 
> Kind#STATEMENT}.
> -???????? * @jls 14.5. Statement.
> +???????? * @jls 14.5 Statements
> ????????? */
> ???????? STATEMENT_SUBKIND(Kind.STATEMENT, true, false),
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/StatementSnippet.java 
> 2019-05-19 12:16:50.421761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/StatementSnippet.java 
> 2019-05-19 12:16:49.985761266 -0700
> @@ -36,7 +36,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 14.5: Statement.
> + * @jls 14.5 Statements
> ? */
> ?public class StatementSnippet extends Snippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/VarSnippet.java 
> 2019-05-19 12:16:51.549761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/VarSnippet.java 
> 2019-05-19 12:16:51.117761266 -0700
> @@ -39,7 +39,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 8.3: FieldDeclaration.
> + * @jls 8.3 Field Declarations
> ? */
> ?public class VarSnippet extends DeclarationSnippet {
>
>


From robert.field at oracle.com  Mon May 20 23:56:01 2019
From: robert.field at oracle.com (Robert Field)
Date: Mon, 20 May 2019 16:56:01 -0700
Subject: JDK 13 RFR of JDK-8224175: Fix inconsistencies in @jls and @jvms
 tags
In-Reply-To: <478b540e-35a0-b9df-8bf3-c03b0422af8f@oracle.com>
References: <478b540e-35a0-b9df-8bf3-c03b0422af8f@oracle.com>
Message-ID: <655efe09-5314-3938-a88f-c11e39166de4@oracle.com>

Thumbs up on the JShell changes.

-Robert


On 5/19/19 12:36 PM, Joe Darcy wrote:
> Hello,
>
> Thanks to some tooling developed by Jon Gibbons, inconsistencies in 
> the section names and numbers in the @jls and @jvms javadoc tags in 
> the jdk and the names and numbers of the current specifications have 
> been identified. These inconsistencies should be fixed.
>
> The names and numbers of the section titles in JLS and JVMS are 
> *mostly* stable, but a few sections have changed most notably for the 
> usage of @jls tags:
>
> ??? * 8.9 "Enum" -> "Enum Type" in Java SE 8
> ??? * 5.1.2 "Widening Primitive Conversions" -> "Widening Primitive 
> *Conversion*" in Java SE 7
>
> Two uses of "@jvms 5.3 Run-time package" refer to the term "Run-time 
> package" defined in that section. The term was replaced by the section 
> name in both cases.
>
> In java.lang.SuppressWarnings, a reference to the section "5.5.2 
> Checked Casts and Unchecked Casts", which was removed in Java SE 9, 
> was replaced with a reference to the enclosing section "5.5. Casting 
> Contexts".
>
> The usage of @jls in jshell was less consistent and has been regularized.
>
> Full webrev at:
>
> ??? http://cr.openjdk.java.net/~darcy/8224175.0/
>
> Patch below.
>
> Thanks,
>
> -Joe
>
> --- old/src/java.base/share/classes/java/lang/Byte.java 2019-05-19 
> 12:16:26.705761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Byte.java 2019-05-19 
> 12:16:26.137761266 -0700
> @@ -356,7 +356,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code short} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public short shortValue() {
> ???????? return (short)value;
> @@ -365,7 +365,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as an {@code int} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -374,7 +374,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code long} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -383,7 +383,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code float} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -392,7 +392,7 @@
> ???? /**
> ????? * Returns the value of this {@code Byte} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/Class.java 2019-05-19 
> 12:16:27.597761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Class.java 2019-05-19 
> 12:16:27.161761266 -0700
> @@ -999,7 +999,7 @@
> ????? *
> ????? * @since 9
> ????? * @spec JPMS
> -???? * @jls 6.7? Fully Qualified Names
> +???? * @jls 6.7 Fully Qualified Names
> ????? */
> ???? public String getPackageName() {
> ???????? String pn = this.packageName;
> @@ -3910,7 +3910,8 @@
> ????? *???????? SecurityManager#checkPackageAccess 
> s.checkPackageAccess()}
> ????? *???????? denies access to the package of the returned class
> ????? * @since 11
> -???? * @jvms 4.7.28 and 4.7.29 NestHost and NestMembers attributes
> +???? * @jvms 4.7.28 The {@code NestHost} Attribute
> +???? * @jvms 4.7.29 The {@code NestMembers} Attribute
> ????? * @jvms 5.4.4 Access Control
> ????? */
> ???? @CallerSensitive
> --- old/src/java.base/share/classes/java/lang/ClassLoader.java 
> 2019-05-19 12:16:28.429761266 -0700
> +++ new/src/java.base/share/classes/java/lang/ClassLoader.java 
> 2019-05-19 12:16:28.041761266 -0700
> @@ -222,7 +222,7 @@
> ? * or a fully qualified name as defined by
> ? * <cite>The Java&trade; Language Specification</cite>.
> ? *
> - * @jls 6.7? Fully Qualified Names
> + * @jls 6.7 Fully Qualified Names
> ? * @jls 13.1 The Form of a Binary
> ? * @see????? #resolveClass(Class)
> ? * @since 1.0
> @@ -2194,7 +2194,7 @@
> ????? * @revised 9
> ????? * @spec JPMS
> ????? *
> -???? * @jvms 5.3 Run-time package
> +???? * @jvms 5.3 Creation and Loading
> ????? * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">
> ????? *????? The JAR File Specification: Package Sealing</a>
> ????? */
> @@ -2228,7 +2228,7 @@
> ????? * @throws? NullPointerException
> ????? *????????? if {@code name} is {@code null}.
> ????? *
> -???? * @jvms 5.3 Run-time package
> +???? * @jvms 5.3 Creation and Loading
> ????? *
> ????? * @since? 9
> ????? * @spec JPMS
> @@ -2255,7 +2255,7 @@
> ????? *???????? this class loader; or an zero length array if no 
> package has been
> ????? *???????? defined by this class loader.
> ????? *
> -???? * @jvms 5.3 Run-time package
> +???? * @jvms 5.3 Creation and Loading
> ????? *
> ????? * @since? 9
> ????? * @spec JPMS
> --- old/src/java.base/share/classes/java/lang/Double.java 2019-05-19 
> 12:16:29.205761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Double.java 2019-05-19 
> 12:16:28.809761266 -0700
> @@ -673,7 +673,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code byte}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.1
> ????? */
> ???? public byte byteValue() {
> @@ -686,7 +686,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code short}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.1
> ????? */
> ???? public short shortValue() {
> @@ -696,7 +696,7 @@
> ???? /**
> ????? * Returns the value of this {@code Double} as an {@code int}
> ????? * after a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code int}
> @@ -711,7 +711,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code long}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -723,7 +723,7 @@
> ????? *
> ????? * @return? the {@code double} value represented by this object
> ????? *????????? converted to type {@code float}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.0
> ????? */
> ???? public float floatValue() {
> --- old/src/java.base/share/classes/java/lang/Float.java 2019-05-19 
> 12:16:30.133761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Float.java 2019-05-19 
> 12:16:29.637761266 -0700
> @@ -602,7 +602,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code byte}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -614,7 +614,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code short}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? * @since 1.1
> ????? */
> ???? public short shortValue() {
> @@ -627,7 +627,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code int}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -639,7 +639,7 @@
> ????? *
> ????? * @return? the {@code float} value represented by this object
> ????? *????????? converted to type {@code long}
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -661,7 +661,7 @@
> ????? *
> ????? * @return the {@code float} value represented by this
> ????? *???????? object converted to type {@code double}
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/FunctionalInterface.java 
> 2019-05-19 12:16:31.105761266 -0700
> +++ new/src/java.base/share/classes/java/lang/FunctionalInterface.java 
> 2019-05-19 12:16:30.609761266 -0700
> @@ -57,7 +57,7 @@
> ? * regardless of whether or not a {@code FunctionalInterface}
> ? * annotation is present on the interface declaration.
> ? *
> - * @jls 4.3.2. The Class Object
> + * @jls 4.3.2 The Class Object
> ? * @jls 9.8 Functional Interfaces
> ? * @jls 9.4.3 Interface Method Body
> ? * @jls 9.6.4.9 @FunctionalInterface
> --- old/src/java.base/share/classes/java/lang/Integer.java 2019-05-19 
> 12:16:31.997761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Integer.java 2019-05-19 
> 12:16:31.529761266 -0700
> @@ -1120,7 +1120,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code byte}
> ????? * after a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -1129,7 +1129,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code short}
> ????? * after a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public short shortValue() {
> ???????? return (short)value;
> @@ -1147,7 +1147,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code long}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? * @see Integer#toUnsignedLong(int)
> ????? */
> ???? public long longValue() {
> @@ -1157,7 +1157,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code float}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -1166,7 +1166,7 @@
> ???? /**
> ????? * Returns the value of this {@code Integer} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/Long.java 2019-05-19 
> 12:16:32.785761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Long.java 2019-05-19 
> 12:16:32.369761266 -0700
> @@ -1339,7 +1339,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code byte} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -1348,7 +1348,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code short} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public short shortValue() {
> ???????? return (short)value;
> @@ -1357,7 +1357,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as an {@code int} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -1375,7 +1375,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code float} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -1384,7 +1384,7 @@
> ???? /**
> ????? * Returns the value of this {@code Long} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/Number.java 2019-05-19 
> 12:16:33.561761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Number.java 2019-05-19 
> 12:16:33.157761266 -0700
> @@ -48,8 +48,8 @@
> ? *
> ? * @author????? Lee Boynton
> ? * @author????? Arthur van Hoff
> - * @jls 5.1.2 Widening Primitive Conversions
> - * @jls 5.1.3 Narrowing Primitive Conversions
> + * @jls 5.1.2 Widening Primitive Conversion
> + * @jls 5.1.3 Narrowing Primitive Conversion
> ? * @since?? 1.0
> ? */
> ?public abstract class Number implements java.io.Serializable {
> --- old/src/java.base/share/classes/java/lang/Package.java 2019-05-19 
> 12:16:34.325761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Package.java 2019-05-19 
> 12:16:33.929761266 -0700
> @@ -108,7 +108,7 @@
> ? * <em>named modules</em>.? Instead those packages are automatically 
> defined
> ? * and have no specification and implementation versioning information.
> ? *
> - * @jvms 5.3 Run-time package
> + * @jvms 5.3 Creation and Loading
> ? * @see <a href="{@docRoot}/../specs/jar/jar.html#package-sealing">
> ? * The JAR File Specification: Package Sealing</a>
> ? * @see ClassLoader#definePackage(String, String, String, String, 
> String, String, String, URL)
> --- old/src/java.base/share/classes/java/lang/Short.java 2019-05-19 
> 12:16:35.109761266 -0700
> +++ new/src/java.base/share/classes/java/lang/Short.java 2019-05-19 
> 12:16:34.701761266 -0700
> @@ -352,7 +352,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code byte} after
> ????? * a narrowing primitive conversion.
> -???? * @jls 5.1.3 Narrowing Primitive Conversions
> +???? * @jls 5.1.3 Narrowing Primitive Conversion
> ????? */
> ???? public byte byteValue() {
> ???????? return (byte)value;
> @@ -370,7 +370,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as an {@code int} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public int intValue() {
> ???????? return (int)value;
> @@ -379,7 +379,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code long} after
> ????? * a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public long longValue() {
> ???????? return (long)value;
> @@ -388,7 +388,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code float}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public float floatValue() {
> ???????? return (float)value;
> @@ -397,7 +397,7 @@
> ???? /**
> ????? * Returns the value of this {@code Short} as a {@code double}
> ????? * after a widening primitive conversion.
> -???? * @jls 5.1.2 Widening Primitive Conversions
> +???? * @jls 5.1.2 Widening Primitive Conversion
> ????? */
> ???? public double doubleValue() {
> ???????? return (double)value;
> --- old/src/java.base/share/classes/java/lang/SuppressWarnings.java 
> 2019-05-19 12:16:35.933761266 -0700
> +++ new/src/java.base/share/classes/java/lang/SuppressWarnings.java 
> 2019-05-19 12:16:35.485761266 -0700
> @@ -49,7 +49,7 @@
> ? * @jls 4.8 Raw Types
> ? * @jls 4.12.2 Variables of Reference Type
> ? * @jls 5.1.9 Unchecked Conversion
> - * @jls 5.5.2 Checked Casts and Unchecked Casts
> + * @jls 5.5 Casting Contexts
> ? * @jls 9.6.4.5 @SuppressWarnings
> ? */
> ?@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE, 
> MODULE})
> --- old/src/java.base/share/classes/java/lang/constant/Constable.java 
> 2019-05-19 12:16:36.717761266 -0700
> +++ new/src/java.base/share/classes/java/lang/constant/Constable.java 
> 2019-05-19 12:16:36.285761266 -0700
> @@ -59,7 +59,7 @@
> ? * method handles, but not necessarily those produced by method handle
> ? * combinators.)
> ? * @jvms 4.4 The Constant Pool
> - * @jvms 4.4.10 The CONSTANT_InvokeDynamic_info Structure
> + * @jvms 4.4.10 The {@code CONSTANT_Dynamic_info} and {@code 
> CONSTANT_InvokeDynamic_info} Structures
> ? *
> ? * @since 12
> ? */
> --- old/src/java.base/share/classes/java/lang/reflect/Method.java 
> 2019-05-19 12:16:37.521761266 -0700
> +++ new/src/java.base/share/classes/java/lang/reflect/Method.java 
> 2019-05-19 12:16:37.117761266 -0700
> @@ -403,7 +403,7 @@
> ????? * @return a string describing this {@code Method}
> ????? *
> ????? * @jls 8.4.3 Method Modifiers
> -???? * @jls 9.4?? Method Declarations
> +???? * @jls 9.4 Method Declarations
> ????? * @jls 9.6.1 Annotation Type Elements
> ????? */
> ???? public String toString() {
> @@ -474,7 +474,7 @@
> ????? * @since 1.5
> ????? *
> ????? * @jls 8.4.3 Method Modifiers
> -???? * @jls 9.4?? Method Declarations
> +???? * @jls 9.4 Method Declarations
> ????? * @jls 9.6.1 Annotation Type Elements
> ????? */
> ???? @Override
> --- old/src/java.base/share/classes/java/lang/reflect/Modifier.java 
> 2019-05-19 12:16:38.353761266 -0700
> +++ new/src/java.base/share/classes/java/lang/reflect/Modifier.java 
> 2019-05-19 12:16:37.917761266 -0700
> @@ -394,7 +394,7 @@
>
> ???? /**
> ????? * The Java source modifiers that can be applied to a field.
> -???? * @jls 8.3.1? Field Modifiers
> +???? * @jls 8.3.1 Field Modifiers
> ????? */
> ???? private static final int FIELD_MODIFIERS =
> ???????? Modifier.PUBLIC???????? | Modifier.PROTECTED??? | 
> Modifier.PRIVATE |
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
> 2019-05-19 12:16:39.161761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java 
> 2019-05-19 12:16:38.757761266 -0700
> @@ -114,7 +114,7 @@
> ? *
> ? * @since 1.8
> ? * @jls 9.6 Annotation Types
> - * @jls 9.6.3.3 @Inherited
> + * @jls 9.6.4.3 {@code @Inherited}
> ? */
> ?public interface AnnotatedConstruct {
> ???? /**
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/element/Element.java 
> 2019-05-19 12:16:40.001761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/element/Element.java 
> 2019-05-19 12:16:39.525761266 -0700
> @@ -196,7 +196,7 @@
> ????? * @see ModuleElement#getEnclosedElements
> ????? * @see Elements#getAllMembers
> ????? * @jls 8.8.9 Default Constructor
> -???? * @jls 8.9 Enums
> +???? * @jls 8.9 Enum Types
> ????? * @revised 9
> ????? * @spec JPMS
> ????? */
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java 
> 2019-05-19 12:16:40.801761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java 
> 2019-05-19 12:16:40.397761266 -0700
> @@ -111,7 +111,7 @@
> ????? * More specifically, an <i>inner</i> type element is any nested 
> type element that
> ????? * is not {@linkplain Modifier#STATIC static}.
> ????? * @return whether or not the constant is nested
> -???? * @jls 14.3 Inner Classes and Enclosing Instances
> +???? * @jls 14.3 Local Class Declarations
> ????? */
> ???? public boolean isNested() {
> ???????? return this != TOP_LEVEL;
> --- 
> old/src/java.compiler/share/classes/javax/lang/model/util/Types.java 
> 2019-05-19 12:16:41.557761266 -0700
> +++ 
> new/src/java.compiler/share/classes/javax/lang/model/util/Types.java 
> 2019-05-19 12:16:41.161761266 -0700
> @@ -104,7 +104,7 @@
> ????? * @return {@code true} if and only if the first type is assignable
> ????? *????????? to the second
> ????? * @throws IllegalArgumentException if given a type for an 
> executable, package, or module
> -???? * @jls 5.2 Assignment Conversion
> +???? * @jls 5.2 Assignment Contexts
> ????? */
> ???? boolean isAssignable(TypeMirror t1, TypeMirror t2);
>
> @@ -115,7 +115,7 @@
> ????? * @param t2? the second type
> ????? * @return {@code true} if and only if the first type contains 
> the second
> ????? * @throws IllegalArgumentException if given a type for an 
> executable, package, or module
> -???? * @jls 4.5.1.1 Type Argument Containment and Equivalence
> +???? * @jls 4.5.1 Type Arguments of Parameterized Types
> ????? */
> ???? boolean contains(TypeMirror t1, TypeMirror t2);
>
> --- 
> old/src/jdk.compiler/share/classes/com/sun/source/tree/BinaryTree.java 
> 2019-05-19 12:16:42.329761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/source/tree/BinaryTree.java 
> 2019-05-19 12:16:41.929761266 -0700
> @@ -40,8 +40,8 @@
> ? * @jls 15.20 Relational Operators
> ? * @jls 15.21 Equality Operators
> ? * @jls 15.22 Bitwise and Logical Operators
> - * @jls 15.23 Conditional-And Operator &&
> - * @jls 15.24 Conditional-Or Operator ||
> + * @jls 15.23 Conditional-And Operator {@code &&}
> + * @jls 15.24 Conditional-Or Operator {@code ||}
> ? *
> ? * @author Peter von der Ah&eacute;
> ? * @author Jonathan Gibbons
> --- 
> old/src/jdk.compiler/share/classes/com/sun/source/tree/ModifiersTree.java 
> 2019-05-19 12:16:43.285761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/source/tree/ModifiersTree.java 
> 2019-05-19 12:16:42.797761266 -0700
> @@ -45,7 +45,7 @@
> ? * @jls 8.5.1 Static Member Type Declarations
> ? * @jls 8.8.3 Constructor Modifiers
> ? * @jls 9.1.1 Interface Modifiers
> - * @jls 9.7?? Annotations
> + * @jls 9.7 Annotations
> ? *
> ? * @author Peter von der Ah&eacute;
> ? * @author Jonathan Gibbons
> --- 
> old/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Types.java 
> 2019-05-19 12:16:44.213761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Types.java 
> 2019-05-19 12:16:43.721761266 -0700
> @@ -2733,7 +2733,7 @@
> ????? * signature</em> of the other.? This is <b>not</b> an equivalence
> ????? * relation.
> ????? *
> -???? * @jls section 8.4.2.
> +???? * @jls 8.4.2 Method Signature
> ????? * @see #overrideEquivalent(Type t, Type s)
> ????? * @param t first signature (possibly raw).
> ????? * @param s second signature (could be subjected to erasure).
> @@ -2752,7 +2752,7 @@
> ????? * equivalence</em>.? This is the natural extension of
> ????? * isSubSignature to an equivalence relation.
> ????? *
> -???? * @jls section 8.4.2.
> +???? * @jls 8.4.2 Method Signature
> ????? * @see #isSubSignature(Type t, Type s)
> ????? * @param t a signature (possible raw, could be subjected to
> ????? * erasure).
> @@ -4214,7 +4214,7 @@
>
> ???? /**
> ????? * Return-Type-Substitutable.
> -???? * @jls section 8.4.5
> +???? * @jls 8.4.5 Method Result
> ????? */
> ???? public boolean returnTypeSubstitutable(Type r1, Type r2) {
> ???????? if (hasSameArgs(r1, r2))
> --- 
> old/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java 
> 2019-05-19 12:16:45.077761266 -0700
> +++ 
> new/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java 
> 2019-05-19 12:16:44.657761266 -0700
> @@ -4222,7 +4222,7 @@
> ????????? * @param tree??? The tree making up the variable reference.
> ????????? * @param env???? The current environment.
> ????????? * @param v?????? The variable's symbol.
> -???????? * @jls? section 8.9 Enums
> +???????? * @jls 8.9 Enum Types
> ????????? */
> ???????? private void checkEnumInitializer(JCTree tree, 
> Env<AttrContext> env, VarSymbol v) {
> ???????????? // JLS:
> --- old/src/jdk.jshell/share/classes/jdk/jshell/ExpressionSnippet.java 
> 2019-05-19 12:16:45.941761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/ExpressionSnippet.java 
> 2019-05-19 12:16:45.505761266 -0700
> @@ -36,7 +36,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 15: Expression.
> + * @jls 15 Expressions
> ? */
> ?public class ExpressionSnippet extends Snippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/ImportSnippet.java 
> 2019-05-19 12:16:47.045761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/ImportSnippet.java 
> 2019-05-19 12:16:46.629761266 -0700
> @@ -36,7 +36,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 8.3: importDeclaration.
> + * @jls 7.5 Import Declarations
> ? */
> ?public class ImportSnippet extends PersistentSnippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/MethodSnippet.java 
> 2019-05-19 12:16:48.501761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/MethodSnippet.java 
> 2019-05-19 12:16:48.093761266 -0700
> @@ -37,7 +37,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 8.4: MethodDeclaration.
> + * @jls 8.4 Method Declarations
> ? */
> ?public class MethodSnippet extends DeclarationSnippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/Snippet.java 
> 2019-05-19 12:16:49.593761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/Snippet.java 
> 2019-05-19 12:16:49.173761266 -0700
> @@ -73,7 +73,7 @@
> ????????? * ({@link 
> jdk.jshell.Snippet.SubKind#SINGLE_STATIC_IMPORT_SUBKIND}) --
> ????????? * use {@link jdk.jshell.Snippet#subKind()} to distinguish.
> ????????? *
> -???????? * @jls 8.3: importDeclaration.
> +???????? * @jls 7.5 Import Declarations
> ????????? * <P>
> ????????? * An import declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -91,7 +91,7 @@
> ????????? * annotation interfaces -- see {@link 
> jdk.jshell.Snippet.SubKind} to
> ????????? * differentiate.
> ????????? *
> -???????? * @jls 7.6: TypeDeclaration.
> +???????? * @jls 7.6 Top Level Type Declarations
> ????????? * <P>
> ????????? * A type declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -101,7 +101,7 @@
> ????????? * A method declaration.
> ????????? * The snippet is an instance of {@link 
> jdk.jshell.MethodSnippet}.
> ????????? *
> -???????? * @jls 8.4: MethodDeclaration.
> +???????? * @jls 8.4 Method Declarations
> ????????? * <P>
> ????????? * A method declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -116,7 +116,7 @@
> ????????? * variable representing an expression -- see
> ????????? * {@link jdk.jshell.Snippet.SubKind}to differentiate.
> ????????? *
> -???????? * @jls 8.3: FieldDeclaration.
> +???????? * @jls 8.3 Field Declarations
> ????????? * <P>
> ????????? * A variable declaration is {@linkplain Kind#isPersistent() 
> persistent}.
> ????????? */
> @@ -133,7 +133,7 @@
> ????????? * All other expression forms (operators, method calls, ...) 
> generate a
> ????????? * scratch variable and so are instead of the VAR Kind.
> ????????? *
> -???????? * @jls 15: Expression.
> +???????? * @jls 15 Expressions
> ????????? */
> ???????? EXPRESSION(false),
>
> @@ -141,7 +141,7 @@
> ????????? * A statement.
> ????????? * The snippet is an instance of {@link 
> jdk.jshell.StatementSnippet}.
> ????????? *
> -???????? * @jls 14.5: Statement.
> +???????? * @jls 14.5 Statements
> ????????? */
> ???????? STATEMENT(false),
>
> @@ -185,99 +185,97 @@
> ???????? /**
> ????????? * Single-Type-Import Declaration.
> ????????? * An import declaration of a single type.
> -???????? * @jls 7.5.1 SingleTypeImportDeclaration.
> +???????? * @jls 7.5.1 Single-Type-Import Declarations
> ????????? */
> ???????? SINGLE_TYPE_IMPORT_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * Type-Import-on-Demand Declaration.
> ????????? * A non-static "star" import.
> -???????? * @jls 7.5.2. TypeImportOnDemandDeclaration.
> +???????? * @jls 7.5.2 Type-Import-on-Demand Declarations
> ????????? */
> ???????? TYPE_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * Single-Static-Import Declaration.
> ????????? * An import of a static member.
> -???????? * @jls 7.5.3 Single-Static-Import.
> +???????? * @jls 7.5.3 Single-Static-Import Declarations
> ????????? */
> ???????? SINGLE_STATIC_IMPORT_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * Static-Import-on-Demand Declaration.
> ????????? * A static "star" import of all static members of a named type.
> -???????? * @jls 7.5.4. Static-Import-on-Demand Static "star" import.
> +???????? * @jls 7.5.4 Static-Import-on-Demand Declarations
> ????????? */
> ???????? STATIC_IMPORT_ON_DEMAND_SUBKIND(Kind.IMPORT),
>
> ???????? /**
> ????????? * A class declaration.
> ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
> -???????? * @jls 8.1. NormalClassDeclaration.
> +???????? * @jls 8.1 Class Declarations
> ????????? */
> ???????? CLASS_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * An interface declaration.
> ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
> -???????? * @jls 9.1. NormalInterfaceDeclaration.
> +???????? * @jls 9.1 Interface Declarations
> ????????? */
> ???????? INTERFACE_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * An enum declaration.
> ????????? * A {@code SubKind} of {@link Kind#TYPE_DECL}.
> -???????? * @jls 8.9. EnumDeclaration.
> +???????? * @jls 8.9 Enum Types
> ????????? */
> ???????? ENUM_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * An annotation interface declaration. A {@code SubKind} of
> ????????? * {@link Kind#TYPE_DECL}.
> -???????? * @jls 9.6. AnnotationTypeDeclaration.
> +???????? * @jls 9.6 Annotation Types
> ????????? */
> ???????? ANNOTATION_TYPE_SUBKIND(Kind.TYPE_DECL),
>
> ???????? /**
> ????????? * A method. The only {@code SubKind} for {@link Kind#METHOD}.
> -???????? * @jls 8.4. MethodDeclaration.
> +???????? * @jls 8.4 Method Declarations
> ????????? */
> ???????? METHOD_SUBKIND(Kind.METHOD),
>
> ???????? /**
> ????????? * A variable declaration without initializer.
> ????????? * A {@code SubKind} of {@link Kind#VAR}.
> -???????? * @jls 8.3. VariableDeclarator without VariableInitializer in
> -???????? * FieldDeclaration.
> +???????? * @jls 8.3 Field Declarations
> ????????? */
> ???????? VAR_DECLARATION_SUBKIND(Kind.VAR, true, true),
>
> ???????? /**
> ????????? * A variable declaration with an initializer expression. A
> ????????? * {@code SubKind} of {@link Kind#VAR}.
> -???????? * @jls 8.3. VariableDeclarator with VariableInitializer in
> -???????? * FieldDeclaration.
> +???????? * @jls 8.3 Field Declarations
> ????????? */
> ???????? VAR_DECLARATION_WITH_INITIALIZER_SUBKIND(Kind.VAR, true, true),
>
> ???????? /**
> ????????? * An expression whose value has been stored in a temporary 
> variable. A
> ????????? * {@code SubKind} of {@link Kind#VAR}.
> -???????? * @jls 15. Primary.
> +???????? * @jls 15 Expressions
> ????????? */
> ???????? TEMP_VAR_EXPRESSION_SUBKIND(Kind.VAR, true, true),
>
> ???????? /**
> ????????? * A simple variable reference expression. A {@code SubKind} of
> ????????? * {@link Kind#EXPRESSION}.
> -???????? * @jls 15.11. Field Access as 3.8. Identifier.
> +???????? * @jls 15.11 Field Access Expressions
> ????????? */
> ???????? VAR_VALUE_SUBKIND(Kind.EXPRESSION, true, true),
>
> ???????? /**
> ????????? * An assignment expression. A {@code SubKind} of
> ????????? * {@link Kind#EXPRESSION}.
> -???????? * @jls 15.26. Assignment.
> +???????? * @jls 15.26 Assignment Operators
> ????????? */
> ???????? ASSIGNMENT_SUBKIND(Kind.EXPRESSION, true, true),
>
> @@ -289,7 +287,7 @@
>
> ???????? /**
> ????????? * A statement. The only {@code SubKind} for {@link 
> Kind#STATEMENT}.
> -???????? * @jls 14.5. Statement.
> +???????? * @jls 14.5 Statements
> ????????? */
> ???????? STATEMENT_SUBKIND(Kind.STATEMENT, true, false),
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/StatementSnippet.java 
> 2019-05-19 12:16:50.421761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/StatementSnippet.java 
> 2019-05-19 12:16:49.985761266 -0700
> @@ -36,7 +36,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 14.5: Statement.
> + * @jls 14.5 Statements
> ? */
> ?public class StatementSnippet extends Snippet {
>
> --- old/src/jdk.jshell/share/classes/jdk/jshell/VarSnippet.java 
> 2019-05-19 12:16:51.549761266 -0700
> +++ new/src/jdk.jshell/share/classes/jdk/jshell/VarSnippet.java 
> 2019-05-19 12:16:51.117761266 -0700
> @@ -39,7 +39,7 @@
> ? * and thus is thread-safe.
> ? *
> ? * @since 9
> - * @jls 8.3: FieldDeclaration.
> + * @jls 8.3 Field Declarations
> ? */
> ?public class VarSnippet extends DeclarationSnippet {
>
>

From robert.field at oracle.com  Tue May 21 02:27:34 2019
From: robert.field at oracle.com (Robert Field)
Date: Mon, 20 May 2019 19:27:34 -0700
Subject: RFR 8223688: JShell: crash on the instantiation of raw anonymous class
Message-ID: <8508cef8-321e-24c0-9a8e-136d5bd24328@oracle.com>

Please review:

Bug: https://bugs.openjdk.java.net/browse/JDK-8223688

Webrev: http://cr.openjdk.java.net/~rfield/8223688.webrev01/


Thanks,
Robert




From robert.field at oracle.com  Fri May 24 05:39:42 2019
From: robert.field at oracle.com (Robert Field)
Date: Thu, 23 May 2019 22:39:42 -0700
Subject: RFR 8199623: JShell: corralling not restored on drop
Message-ID: <af8e40f8-50e2-d91f-cfda-6cbb83d2a2ba@oracle.com>

Please review --

Bug: https://bugs.openjdk.java.net/browse/JDK-8199623

Webrev: http://cr.openjdk.java.net/~rfield/8199623.webrev01/


Thanks,
Robert


From TOSHIONA at jp.ibm.com  Fri May 24 06:47:15 2019
From: TOSHIONA at jp.ibm.com (Toshio 5 Nakamura)
Date: Fri, 24 May 2019 15:47:15 +0900
Subject: RFR: 8224184: jshell got IOException at exiting with AIX
In-Reply-To: <OF6FAA0433.E1E08D96-ON00258400.002C5B08-49258400.002D1A74@notes.na.collabserv.com>
References: <OF6FAA0433.E1E08D96-ON00258400.002C5B08-49258400.002D1A74@notes.na.collabserv.com>
Message-ID: <OF48E3CD24.3805AEDF-ON00258404.0024C587-49258404.0025492D@notes.na.collabserv.com>

Hi,

I think lacking of testcase may be a concern of my proposal.
Honestly, I couldn't create an automated testcase of this problem.
I tried to use shell script like below, but it cannot execute the
problematic path.

$ echo "/exit" | jshell

I think the testcase needs to run on 'pty'.

Manual instructions are very simple, though.
1. Open a terminal on AIX (or telnet/ssh to AIX)
2. Launch jshell
3. Type "/exit"

Could you give me any advice?

Issue: https://bugs.openjdk.java.net/browse/JDK-8224184
Webrev: http://cr.openjdk.java.net/~tnakamura/8224184/webrev.00/

Thanks,
Toshio Nakamura
IBM Japan

> From: "Toshio 5 Nakamura" <TOSHIONA at jp.ibm.com>
> To: kulla-dev at openjdk.java.net
> Date: 2019/05/20 17:13
> Subject: [EXTERNAL] RFR: 8224184: jshell got IOException at exiting with
AIX
> Sent by: "kulla-dev" <kulla-dev-bounces at openjdk.java.net>
>
>
> Hi,
>
> Could you review JDK-8224184: jshell got IOException at exiting with AIX?
> Also, I'd like to have a sponsor of the patch (I'm an author).
>
> Issue: https://urldefense.proofpoint.com/v2/url?
>
u=https-3A__bugs.openjdk.java.net_browse_JDK-2D8224184&d=DwIFAg&c=jf_iaSHvJObTbx-

> siA1ZOg&r=EVbFABcgo-X99_TGI2-
>
qsMtyulHUruf8lAzMlVpVRqw&m=t8kIXQoVdkkBGhnWC09eRlCUxlXUlvabknJjA5SSotI&s=9LIfd1v5UBKEvYKAIm6tDtqYTlD6QK-

> jRl1I8HHIu5g&e=
> Webrev: https://urldefense.proofpoint.com/v2/url?
> u=http-3A__cr.openjdk.java.net_-7Etnakamura_8224184_webrev.
> 00&d=DwIFAg&c=jf_iaSHvJObTbx-siA1ZOg&r=EVbFABcgo-X99_TGI2-
>
qsMtyulHUruf8lAzMlVpVRqw&m=t8kIXQoVdkkBGhnWC09eRlCUxlXUlvabknJjA5SSotI&s=VC54L6HMLzUBB-3DcRQdr55JQda5wgw8r9SgxOvjkvA&e=

>
> AIX doesn't show "min" or "time" by "stty -a" when "icanon" is defined.
> This caused invalid value was trying to be set, and IOException was
thrown.
>
> Thanks,
> Toshio Nakamura
>

From jonathan.gibbons at oracle.com  Thu May 30 20:44:32 2019
From: jonathan.gibbons at oracle.com (Jonathan Gibbons)
Date: Thu, 30 May 2019 13:44:32 -0700
Subject: Use of @jls in jshell
Message-ID: <36d5b63a-3680-c026-d856-c6f515c0782c@oracle.com>

Joe, Robert,

We recently changed the support for the @jls tag, and I note that it 
conflicts with a style of usage that we did not detect previously with 
line-based tools (i.e. grep.)

This is one of a few similar occurrences in Snippet.java


 ???????? * @jls 8.3 Field Declarations
 ???????? * <P>
 ???????? * A variable declaration is {@linkplain Kind#isPersistent() 
persistent}.

The problem is that as it currently stands, the @jls tag will detect the 
8.3 and then attempt to put a`<a href=...>` ... `</a>` aound the rest of 
the content. That's bad in this case, because you can't have `<P>` 
inside `<a>`.


There are two ways forward:

1. Remove the extra text, and/or restructure the doc comment so that the 
extra text is not part of @jls

2. Maybe update the @jls taglet to modify its behavior in the face of 
more complex HTML content.

My reading of the document is that these paragraphs should be moved 
before the @jls reference, because they do not appear to be part of the 
@jls reference.

Comments, suggestions?

-- Jon


From jan.lahoda at oracle.com  Fri May 31 07:47:41 2019
From: jan.lahoda at oracle.com (Jan Lahoda)
Date: Fri, 31 May 2019 09:47:41 +0200
Subject: RFR 8080353: JShell: Better error message on attempting to add
 default method
In-Reply-To: <eb8be6c5-e90a-055f-0e0c-337faea355c8@oracle.com>
References: <eb8be6c5-e90a-055f-0e0c-337faea355c8@oracle.com>
Message-ID: <a8fa4757-8bf5-b789-04be-6528d1daeb9b@oracle.com>

Looks good to me. Maybe it would be useful to add a test where default 
is combined with public? No need for re-review.

Jan

On 18. 05. 19 23:08, Robert Field wrote:
> Please review...
> 
> Bug: https://bugs.openjdk.java.net/browse/JDK-8080353
> 
> Webrev: http://cr.openjdk.java.net/~rfield/8080353.webrev/
> 
> Thanks,
> Robert
> 
> 

From jan.lahoda at oracle.com  Fri May 31 08:02:02 2019
From: jan.lahoda at oracle.com (Jan Lahoda)
Date: Fri, 31 May 2019 10:02:02 +0200
Subject: RFR 8223688: JShell: crash on the instantiation of raw anonymous
 class
In-Reply-To: <8508cef8-321e-24c0-9a8e-136d5bd24328@oracle.com>
References: <8508cef8-321e-24c0-9a8e-136d5bd24328@oracle.com>
Message-ID: <d8a823bb-f72d-7671-2960-1e2cfbb05028@oracle.com>

Looks good to me.

Jan

On 21. 05. 19 4:27, Robert Field wrote:
> Please review:
> 
> Bug: https://bugs.openjdk.java.net/browse/JDK-8223688
> 
> Webrev: http://cr.openjdk.java.net/~rfield/8223688.webrev01/
> 
> 
> Thanks,
> Robert
> 
> 
>