8249687: Use inline @jls and @jvm tages in more places in java.base

Reviewed-by: bpb, mchung, mikael

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2020, 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
@@ -34,7 +34,7 @@ package java.lang;
  *     new AssertionError(<i>expression</i>)
  * </pre>
  * has as its detail message the <i>string conversion</i> of
- * <i>expression</i> (as defined in section 15.18.1.1 of
+ * <i>expression</i> (as defined in section {@jls 5.1.11} of
  * <cite>The Java Language Specification</cite>),
  * regardless of the type of <i>expression</i>.
  *
@@ -62,7 +62,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified object, which is converted to a string as
-     * defined in section 15.18.1.1 of
+     * defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *<p>
      * If the specified object is an instance of {@code Throwable}, it
@@ -80,7 +80,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified {@code boolean}, which is converted to
-     * a string as defined in section 15.18.1.1 of
+     * a string as defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *
      * @param detailMessage value to be used in constructing detail message
@@ -92,7 +92,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified {@code char}, which is converted to a
-     * string as defined in section 15.18.1.1 of
+     * string as defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *
      * @param detailMessage value to be used in constructing detail message
@@ -104,7 +104,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified {@code int}, which is converted to a
-     * string as defined in section 15.18.1.1 of
+     * string as defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *
      * @param detailMessage value to be used in constructing detail message
@@ -116,7 +116,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified {@code long}, which is converted to a
-     * string as defined in section 15.18.1.1 of
+     * string as defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *
      * @param detailMessage value to be used in constructing detail message
@@ -128,7 +128,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified {@code float}, which is converted to a
-     * string as defined in section 15.18.1.1 of
+     * string as defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *
      * @param detailMessage value to be used in constructing detail message
@@ -140,7 +140,7 @@ public class AssertionError extends Error {
     /**
      * Constructs an AssertionError with its detail message derived
      * from the specified {@code double}, which is converted to a
-     * string as defined in section 15.18.1.1 of
+     * string as defined in section {@jls 5.1.11} of
      * <cite>The Java Language Specification</cite>.
      *
      * @param detailMessage value to be used in constructing detail message

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

@@ -289,7 +289,7 @@ public final class Byte extends Number implements Comparable<Byte>, Constable {
      * </blockquote>
      *
      * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>
-     * are as defined in section 3.10.1 of
+     * are as defined in section {@jls 3.10.1} of
      * <cite>The Java Language Specification</cite>,
      * except that underscores are not accepted between digits.
      *

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

@@ -2531,7 +2531,7 @@ public abstract class ClassLoader {
      *         The name of the package whose package default assertion status
      *         is to be set. A {@code null} value indicates the unnamed
      *         package that is "current"
-     *         (see section 7.4.2 of
+     *         (see section {@jls 7.4.2} of
      *         <cite>The Java Language Specification</cite>.)
      *
      * @param  enabled

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2020, 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
@@ -1376,7 +1376,7 @@ public final class Integer extends Number
      * </blockquote>
      *
      * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>
-     * are as defined in section 3.10.1 of
+     * are as defined in section {@jls 3.10.1} of
      * <cite>The Java Language Specification</cite>,
      * except that underscores are not accepted between digits.
      *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2020, 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
@@ -1228,7 +1228,7 @@ public final class Long extends Number
      * </blockquote>
      *
      * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>
-     * are as defined in section 3.10.1 of
+     * are as defined in section {@jls 3.10.1} of
      * <cite>The Java Language Specification</cite>,
      * except that underscores are not accepted between digits.
      *

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

@@ -85,7 +85,7 @@ import sun.security.util.SecurityConstants;
  *
  * <p> The package names that are parameters or returned by methods defined in
  * this class are the fully-qualified names of the packages as defined in
- * section 6.5.3 of <cite>The Java Language Specification</cite>, for
+ * section {@jls 6.5.3} of <cite>The Java Language Specification</cite>, for
  * example, {@code "java.lang"}. </p>
  *
  * <p> Unless otherwise specified, passing a {@code null} argument to a method
@@ -672,7 +672,7 @@ public final class Module implements AnnotatedElement {
      * <p> This method has no effect if the package is already exported (or
      * <em>open</em>) to the given module. </p>
      *
-     * @apiNote As specified in section 5.4.3 of the <cite>The Java
+     * @apiNote As specified in section {@jvms 5.4.3} of the <cite>The Java
      * Virtual Machine Specification </cite>, if an attempt to resolve a
      * symbolic reference fails because of a linkage error, then subsequent
      * attempts to resolve the reference always fail with the same error that

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

@@ -121,7 +121,7 @@ public class Package extends NamedPackage implements java.lang.reflect.Annotated
     /**
      * Return the name of this package.
      *
-     * @return  The fully-qualified name of this package as defined in section 6.5.3 of
+     * @return  The fully-qualified name of this package as defined in section {@jls 6.5.3} of
      *          <cite>The Java Language Specification</cite>,
      *          for example, {@code java.lang}
      */

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

@@ -294,7 +294,7 @@ public final class Short extends Number implements Comparable<Short>, Constable
      * </blockquote>
      *
      * <i>DecimalNumeral</i>, <i>HexDigits</i>, and <i>OctalDigits</i>
-     * are as defined in section 3.10.1 of
+     * are as defined in section {@jls 3.10.1} of
      * <cite>The Java Language Specification</cite>,
      * except that underscores are not accepted between digits.
      *

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

@@ -153,8 +153,8 @@ public final class StackTraceElement implements java.io.Serializable {
      * Returns the name of the source file containing the execution point
      * represented by this stack trace element.  Generally, this corresponds
      * to the {@code SourceFile} attribute of the relevant {@code class}
-     * file (as per <i>The Java Virtual Machine Specification</i>, Section
+     * file (as per <cite>The Java Virtual Machine Specification</cite>, Section
-     * 4.7.7).  In some systems, the name may refer to some source code unit
+     * {@jvms 4.7.7}).  In some systems, the name may refer to some source code unit
      * other than a file, such as an entry in source repository.
      *
      * @return the name of the file containing the execution point
@@ -169,8 +169,8 @@ public final class StackTraceElement implements java.io.Serializable {
      * Returns the line number of the source line containing the execution
      * point represented by this stack trace element.  Generally, this is
      * derived from the {@code LineNumberTable} attribute of the relevant
-     * {@code class} file (as per <i>The Java Virtual Machine
+     * {@code class} file (as per <cite>The Java Virtual Machine
-     * Specification</i>, Section 4.7.8).
+     * Specification</cite>, Section {@jvms 4.7.8}).
      *
      * @return the line number of the source line containing the execution
      *         point represented by this stack trace element, or a negative
@@ -242,8 +242,8 @@ public final class StackTraceElement implements java.io.Serializable {
      * represented by this stack trace element.  If the execution point is
      * contained in an instance or class initializer, this method will return
      * the appropriate <i>special method name</i>, {@code <init>} or
-     * {@code <clinit>}, as per Section 3.9 of <i>The Java Virtual
+     * {@code <clinit>}, as per Section {@jvms 3.9} of <cite>The Java Virtual
-     * Machine Specification</i>.
+     * Machine Specification</cite>.
      *
      * @return the name of the method containing the execution point
      *         represented by this stack trace element.

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

@@ -3533,12 +3533,11 @@ public final class String
      * if and only if {@code s.equals(t)} is {@code true}.
      * <p>
      * All literal strings and string-valued constant expressions are
-     * interned. String literals are defined in section 3.10.5 of the
+     * interned. String literals are defined in section {@jls 3.10.5} of the
      * <cite>The Java Language Specification</cite>.
      *
      * @return  a string that has the same contents as this string, but is
      *          guaranteed to be from a pool of unique strings.
-     * @jls 3.10.5 String Literals
      */
     public native String intern();
 

src/java.base/share/classes/java/lang/ref/Reference.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2020, 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
@@ -418,7 +418,7 @@ public abstract class Reference<T> {
      * {@code synchronized} blocks or methods, or using other synchronization
      * facilities are not possible or do not provide the desired control.  This
      * method is applicable only when reclamation may have visible effects,
-     * which is possible for objects with finalizers (See Section 12.6
+     * which is possible for objects with finalizers (See Section {@jls 12.6}
      * of <cite>The Java Language Specification</cite>) that
      * are implemented in ways that rely on ordering control for
      * correctness.

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

@@ -436,7 +436,7 @@ public final class Constructor<T> extends Executable {
      *
      * <p>If the constructor's declaring class is an inner class in a
      * non-static context, the first argument to the constructor needs
-     * to be the enclosing instance; see section 15.9.3 of
+     * to be the enclosing instance; see section {@jls 15.9.3} of
      * <cite>The Java Language Specification</cite>.
      *
      * <p>If the required access and argument checks succeed and the

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

@@ -32,7 +32,8 @@ import java.util.StringJoiner;
  * constants to decode class and member access modifiers.  The sets of
  * modifiers are represented as integers with distinct bit positions
  * representing different modifiers.  The values for the constants
- * representing the modifiers are taken from the tables in sections 4.1, 4.4, 4.5, and 4.7 of
+ * representing the modifiers are taken from the tables in sections
+ * {@jvms 4.1}, {@jvms 4.4}, {@jvms 4.5}, and {@jvms 4.7} of
  * <cite>The Java Virtual Machine Specification</cite>.
  *
  * @see Class#getModifiers()

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

@@ -392,7 +392,7 @@ final class ProxyGenerator extends ClassWriter {
     /**
      * Return the number of abstract "words", or consecutive local variable
      * indexes, required to contain a value of the given type.  See JVMS
-     * section 3.6.1.
+     * section {@jvms 3.6.1}.
      * <p>
      * Note that the original version of the JVMS contained a definition of
      * this abstract notion of a "word" in section 3.4, but that definition

src/java.base/share/classes/java/util/Properties.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2020, 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
@@ -94,7 +94,7 @@ import jdk.internal.util.xml.PropertiesDefaultHandler;
  * methods work the same way as the load(Reader)/store(Writer, String) pair, except
  * the input/output stream is encoded in ISO 8859-1 character encoding.
  * Characters that cannot be directly represented in this encoding can be written using
- * Unicode escapes as defined in section 3.3 of
+ * Unicode escapes as defined in section {@jls 3.3} of
  * <cite>The Java Language Specification</cite>;
  * only a single 'u' character is allowed in an escape
  * sequence.
@@ -336,7 +336,7 @@ public class Properties extends Hashtable<Object,Object> {
      * <a id="unicodeescapes"></a>
      * Characters in keys and elements can be represented in escape
      * sequences similar to those used for character and string literals
-     * (see sections 3.3 and 3.10.6 of
+     * (see sections {@jls 3.3} and {@jls 3.10.6} of
      * <cite>The Java Language Specification</cite>).
      *
      * The differences from the character escape sequences and Unicode
@@ -390,7 +390,7 @@ public class Properties extends Hashtable<Object,Object> {
      * the ISO 8859-1 character encoding; that is each byte is one Latin1
      * character. Characters not in Latin1, and certain special characters,
      * are represented in keys and elements using Unicode escapes as defined in
-     * section 3.3 of
+     * section {@jls 3.3} of
      * <cite>The Java Language Specification</cite>.
      * <p>
      * The specified stream remains open after this method returns.

src/java.base/share/classes/java/util/PropertyResourceBundle.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2020, 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
@@ -120,7 +120,7 @@ import sun.util.ResourceBundleEnumeration;
  * and throws the exception if it encounters an invalid sequence.
  * If "ISO-8859-1" is specified, characters that cannot be represented in
  * ISO-8859-1 encoding must be represented by Unicode Escapes as defined in section
- * 3.3 of <cite>The Java Language Specification</cite>
+ * {@jls 3.3} of <cite>The Java Language Specification</cite>
  * whereas the other constructor which takes a {@code Reader} does not have that limitation.
  * Other encoding values are ignored for this system property.
  * The system property is read and evaluated when initializing this class.

src/java.base/share/classes/java/util/regex/Pattern.java

@@ -396,7 +396,7 @@ import jdk.internal.util.ArraysSupport;
  * <p> Backslashes within string literals in Java source code are interpreted
  * as required by
  * <cite>The Java Language Specification</cite>
- * as either Unicode escapes (section 3.3) or other character escapes (section 3.10.6)
+ * as either Unicode escapes (section {@jls 3.3}) or other character escapes (section {@jls 3.10.6})
  * It is therefore necessary to double backslashes in string
  * literals that represent regular expressions to protect them from
  * interpretation by the Java bytecode compiler.  The string literal
@@ -543,7 +543,7 @@ import jdk.internal.util.ArraysSupport;
  * Canonical Equivalents and RL2.2 Extended Grapheme Clusters.
  * <p>
  * <b>Unicode escape sequences</b> such as <code>&#92;u2014</code> in Java source code
- * are processed as described in section 3.3 of
+ * are processed as described in section {@jls 3.3} of
  * <cite>The Java Language Specification</cite>.
  * Such escape sequences are also implemented directly by the regular-expression
  * parser so that Unicode escapes can be used in expressions that are read from