JDK 13 RFR of JDK-8224175: Fix inconsistencies in @jls and @jvms tags

Joe Darcy joe.darcy at oracle.com
Sun May 19 19:36:55 UTC 2019


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™ 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é
   * @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é
   * @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 {




More information about the core-libs-dev mailing list