8249687: Use inline @jls and @jvm tages in more places in java.base
Reviewed-by: bpb, mchung, mikael
diff --git a/src/java.base/share/classes/java/lang/AssertionError.java b/src/java.base/share/classes/java/lang/AssertionError.java
index 704e774..546b0cb 100644
--- a/src/java.base/share/classes/java/lang/AssertionError.java
+++ b/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 @@
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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 @@
/**
* 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
diff --git a/src/java.base/share/classes/java/lang/Byte.java b/src/java.base/share/classes/java/lang/Byte.java
index 98c2ef4..e71eba7 100644
--- a/src/java.base/share/classes/java/lang/Byte.java
+++ b/src/java.base/share/classes/java/lang/Byte.java
@@ -289,7 +289,7 @@
* </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.
*
diff --git a/src/java.base/share/classes/java/lang/ClassLoader.java b/src/java.base/share/classes/java/lang/ClassLoader.java
index d8bd0ee..aff4857 100644
--- a/src/java.base/share/classes/java/lang/ClassLoader.java
+++ b/src/java.base/share/classes/java/lang/ClassLoader.java
@@ -2531,7 +2531,7 @@
* 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
diff --git a/src/java.base/share/classes/java/lang/Integer.java b/src/java.base/share/classes/java/lang/Integer.java
index 6f6b845..cf67cc4 100644
--- a/src/java.base/share/classes/java/lang/Integer.java
+++ b/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 @@
* </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.
*
diff --git a/src/java.base/share/classes/java/lang/Long.java b/src/java.base/share/classes/java/lang/Long.java
index 4a51ae2..953f352 100644
--- a/src/java.base/share/classes/java/lang/Long.java
+++ b/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 @@
* </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.
*
diff --git a/src/java.base/share/classes/java/lang/Module.java b/src/java.base/share/classes/java/lang/Module.java
index 32279ba4..119621c 100644
--- a/src/java.base/share/classes/java/lang/Module.java
+++ b/src/java.base/share/classes/java/lang/Module.java
@@ -85,7 +85,7 @@
*
* <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 @@
* <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
diff --git a/src/java.base/share/classes/java/lang/Package.java b/src/java.base/share/classes/java/lang/Package.java
index e359881..934bc0e 100644
--- a/src/java.base/share/classes/java/lang/Package.java
+++ b/src/java.base/share/classes/java/lang/Package.java
@@ -121,7 +121,7 @@
/**
* 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}
*/
diff --git a/src/java.base/share/classes/java/lang/Short.java b/src/java.base/share/classes/java/lang/Short.java
index 2824c2d..53ca694 100644
--- a/src/java.base/share/classes/java/lang/Short.java
+++ b/src/java.base/share/classes/java/lang/Short.java
@@ -294,7 +294,7 @@
* </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.
*
diff --git a/src/java.base/share/classes/java/lang/StackTraceElement.java b/src/java.base/share/classes/java/lang/StackTraceElement.java
index cbbae0e..b23aafb 100644
--- a/src/java.base/share/classes/java/lang/StackTraceElement.java
+++ b/src/java.base/share/classes/java/lang/StackTraceElement.java
@@ -153,8 +153,8 @@
* 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
- * 4.7.7). In some systems, the name may refer to some source code unit
+ * file (as per <cite>The Java Virtual Machine Specification</cite>, Section
+ * {@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 @@
* 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
- * Specification</i>, Section 4.7.8).
+ * {@code class} file (as per <cite>The Java Virtual Machine
+ * 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 @@
* 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
- * Machine Specification</i>.
+ * {@code <clinit>}, as per Section {@jvms 3.9} of <cite>The Java Virtual
+ * Machine Specification</cite>.
*
* @return the name of the method containing the execution point
* represented by this stack trace element.
diff --git a/src/java.base/share/classes/java/lang/String.java b/src/java.base/share/classes/java/lang/String.java
index 8ed94e7..8ef0a423 100644
--- a/src/java.base/share/classes/java/lang/String.java
+++ b/src/java.base/share/classes/java/lang/String.java
@@ -3533,12 +3533,11 @@
* 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();
diff --git a/src/java.base/share/classes/java/lang/ref/Reference.java b/src/java.base/share/classes/java/lang/ref/Reference.java
index 9e41aac..fa3d699 100644
--- a/src/java.base/share/classes/java/lang/ref/Reference.java
+++ b/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 @@
* {@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.
diff --git a/src/java.base/share/classes/java/lang/reflect/Constructor.java b/src/java.base/share/classes/java/lang/reflect/Constructor.java
index d762d31..45a7cb0 100644
--- a/src/java.base/share/classes/java/lang/reflect/Constructor.java
+++ b/src/java.base/share/classes/java/lang/reflect/Constructor.java
@@ -436,7 +436,7 @@
*
* <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
diff --git a/src/java.base/share/classes/java/lang/reflect/Modifier.java b/src/java.base/share/classes/java/lang/reflect/Modifier.java
index 1355a6c..3d1cd30 100644
--- a/src/java.base/share/classes/java/lang/reflect/Modifier.java
+++ b/src/java.base/share/classes/java/lang/reflect/Modifier.java
@@ -32,7 +32,8 @@
* 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()
diff --git a/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java b/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java
index 2ae0911..ce627f1 100644
--- a/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java
+++ b/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java
@@ -392,7 +392,7 @@
/**
* 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
diff --git a/src/java.base/share/classes/java/util/Properties.java b/src/java.base/share/classes/java/util/Properties.java
index 2f4bc9d..e67042b 100644
--- a/src/java.base/share/classes/java/util/Properties.java
+++ b/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 @@
* 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 @@
* <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 @@
* 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.
diff --git a/src/java.base/share/classes/java/util/PropertyResourceBundle.java b/src/java.base/share/classes/java/util/PropertyResourceBundle.java
index fba731b..108507d 100644
--- a/src/java.base/share/classes/java/util/PropertyResourceBundle.java
+++ b/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 @@
* 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.
diff --git a/src/java.base/share/classes/java/util/regex/Pattern.java b/src/java.base/share/classes/java/util/regex/Pattern.java
index 8b9fbf2..c0ccc53 100644
--- a/src/java.base/share/classes/java/util/regex/Pattern.java
+++ b/src/java.base/share/classes/java/util/regex/Pattern.java
@@ -396,7 +396,7 @@
* <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 @@
* Canonical Equivalents and RL2.2 Extended Grapheme Clusters.
* <p>
* <b>Unicode escape sequences</b> such as <code>\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
