8283234: Improve @jls usage in java.base

Reviewed-by: iris

src/java.base/share/classes/java/lang/StringConcatHelper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -430,7 +430,7 @@ static String simpleConcat(Object first, Object second) {
      * Produce a String from a concatenation of single argument, which we
      * end up using for trivial concatenations like {@code "" + arg}.
      *
-     * This will always create a new Object to comply with JLS 15.18.1:
+     * This will always create a new Object to comply with JLS {@jls 15.18.1}:
      * "The String object is newly created unless the expression is a
      * compile-time constant expression".
      *

src/java.base/share/classes/java/lang/invoke/MethodHandle.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2008, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2008, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -807,15 +807,15 @@ public Object invokeWithArguments(java.util.List<?> arguments) throws Throwable
      *     (The types do not need to be related in any particular way.
      *     This is because a dynamic value of null can convert to any reference type.)
      * <li>If <em>T0</em> and <em>T1</em> are primitives, then a Java method invocation
-     *     conversion (JLS 5.3) is applied, if one exists.
+     *     conversion (JLS {@jls 5.3}) is applied, if one exists.
      *     (Specifically, <em>T0</em> must convert to <em>T1</em> by a widening primitive conversion.)
      * <li>If <em>T0</em> is a primitive and <em>T1</em> a reference,
-     *     a Java casting conversion (JLS 5.5) is applied if one exists.
+     *     a Java casting conversion (JLS {@jls 5.5}) is applied if one exists.
      *     (Specifically, the value is boxed from <em>T0</em> to its wrapper class,
      *     which is then widened as needed to <em>T1</em>.)
      * <li>If <em>T0</em> is a reference and <em>T1</em> a primitive, an unboxing
      *     conversion will be applied at runtime, possibly followed
-     *     by a Java method invocation conversion (JLS 5.3)
+     *     by a Java method invocation conversion (JLS {@jls 5.3})
      *     on the primitive value.  (These are the primitive widening conversions.)
      *     <em>T0</em> must be a wrapper class or a supertype of one.
      *     (In the case where <em>T0</em> is Object, these are the conversions

src/java.base/share/classes/java/lang/invoke/MethodHandles.java

@@ -1884,7 +1884,7 @@ public enum ClassOption {
              * as a normal class or interface has with its own defining loader.
              * This means that the hidden class may be unloaded if and only if
              * its defining loader is not reachable and thus may be reclaimed
-             * by a garbage collector (JLS 12.7).
+             * by a garbage collector (JLS {@jls 12.7}).
              *
              * <p> By default, a hidden class or interface may be unloaded
              * even if the class loader that is marked as its defining loader is
@@ -2024,7 +2024,7 @@ static int optionsToFlag(Set<ClassOption> options) {
          * that {@linkplain Class#getClassLoader() defined it}.
          * This means that a class created by a class loader may be unloaded if and
          * only if its defining loader is not reachable and thus may be reclaimed
-         * by a garbage collector (JLS 12.7).
+         * by a garbage collector (JLS {@jls 12.7}).
          *
          * By default, however, a hidden class or interface may be unloaded even if
          * the class loader that is marked as its defining loader is
@@ -4757,15 +4757,15 @@ static MethodHandle basicInvoker(MethodType type) {
      *     the boolean is converted to a byte value, 1 for true, 0 for false.
      *     (This treatment follows the usage of the bytecode verifier.)
      * <li>If <em>T1</em> is boolean and <em>T0</em> is another primitive,
-     *     <em>T0</em> is converted to byte via Java casting conversion (JLS 5.5),
+     *     <em>T0</em> is converted to byte via Java casting conversion (JLS {@jls 5.5}),
      *     and the low order bit of the result is tested, as if by {@code (x & 1) != 0}.
      * <li>If <em>T0</em> and <em>T1</em> are primitives other than boolean,
-     *     then a Java casting conversion (JLS 5.5) is applied.
+     *     then a Java casting conversion (JLS {@jls 5.5}) is applied.
      *     (Specifically, <em>T0</em> will convert to <em>T1</em> by
      *     widening and/or narrowing.)
      * <li>If <em>T0</em> is a reference and <em>T1</em> a primitive, an unboxing
      *     conversion will be applied at runtime, possibly followed
-     *     by a Java casting conversion (JLS 5.5) on the primitive value,
+     *     by a Java casting conversion (JLS {@jls 5.5}) on the primitive value,
      *     possibly followed by a conversion from byte to boolean by testing
      *     the low-order bit.
      * <li>If <em>T0</em> is a reference and <em>T1</em> a primitive,

src/java.base/share/classes/java/lang/invoke/StringConcatFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2015, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -142,10 +142,10 @@ public final class StringConcatFactory {
      * <ul>
      *     <li>zero inputs, concatenation results in an empty string;</li>
      *     <li>one input, concatenation results in the single
-     *     input converted as per JLS 5.1.11 "String Conversion"; otherwise</li>
+     *     input converted as per JLS {@jls 5.1.11} "String Conversion"; otherwise</li>
      *     <li>two or more inputs, the inputs are concatenated as per
-     *     requirements stated in JLS 15.18.1 "String Concatenation Operator +".
-     *     The inputs are converted as per JLS 5.1.11 "String Conversion",
+     *     requirements stated in JLS {@jls 15.18.1} "String Concatenation Operator +".
+     *     The inputs are converted as per JLS {@jls 5.1.11} "String Conversion",
      *     and combined from left to right.</li>
      * </ul>
      *
@@ -223,10 +223,10 @@ public static CallSite makeConcat(MethodHandles.Lookup lookup,
      * <ul>
      *     <li>zero inputs, concatenation results in an empty string;</li>
      *     <li>one input, concatenation results in the single
-     *     input converted as per JLS 5.1.11 "String Conversion"; otherwise</li>
+     *     input converted as per JLS {@jls 5.1.11} "String Conversion"; otherwise</li>
      *     <li>two or more inputs, the inputs are concatenated as per
-     *     requirements stated in JLS 15.18.1 "String Concatenation Operator +".
-     *     The inputs are converted as per JLS 5.1.11 "String Conversion",
+     *     requirements stated in JLS {@jls 15.18.1} "String Concatenation Operator +".
+     *     The inputs are converted as per JLS {@jls 5.1.11} "String Conversion",
      *     and combined from left to right.</li>
      * </ul>
      *

src/java.base/share/classes/java/lang/reflect/TypeVariable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -30,8 +30,8 @@
  * A type variable is created the first time it is needed by a reflective
  * method, as specified in this package.  If a type variable t is referenced
  * by a type (i.e, class, interface or annotation type) T, and T is declared
- * by the nth enclosing class of T (see JLS 8.1.2), then the creation of t
- * requires the resolution (see JVMS 5) of the ith enclosing class of T,
+ * by the n<sup>th</sup> enclosing class of T (see JLS {@jls 8.1.2}), then the creation of t
+ * requires the resolution (see JVMS {@jvms 5}) of the i<sup>th</sup> enclosing class of T,
  * for i = 0 to n, inclusive. Creating a type variable must not cause the
  * creation of its bounds. Repeated creation of a type variable has no effect.
  *