JDK 16 RFR of JDK-8249687: Use inline @jls and @jvm tages in more places in java.base
Joe Darcy
joe.darcy at oracle.com
Fri Jul 17 23:04:08 UTC 2020
A few more cases found with scripted assistance from Mikael; updated webrev:
http://cr.openjdk.java.net/~darcy/8249687.1
Patches for new files below.
Thanks,
-Joe
--- old/src/java.base/share/classes/java/lang/StackTraceElement.java
2020-07-17 15:54:09.036893982 -0700
+++ new/src/java.base/share/classes/java/lang/StackTraceElement.java
2020-07-17 15:54:08.316893982 -0700
@@ -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.
--- old/src/java.base/share/classes/java/lang/String.java 2020-07-17
15:54:10.200893982 -0700
+++ new/src/java.base/share/classes/java/lang/String.java 2020-07-17
15:54:09.576893982 -0700
@@ -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();
--- old/src/java.base/share/classes/java/lang/ref/Reference.java
2020-07-17 15:54:11.504893982 -0700
+++ new/src/java.base/share/classes/java/lang/ref/Reference.java
2020-07-17 15:54:10.792893982 -0700
@@ -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.
--- old/src/java.base/share/classes/java/lang/reflect/Constructor.java
2020-07-17 15:54:12.664893982 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Constructor.java
2020-07-17 15:54:12.064893982 -0700
@@ -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
--- old/src/java.base/share/classes/java/lang/reflect/Modifier.java
2020-07-17 15:54:13.864893982 -0700
+++ new/src/java.base/share/classes/java/lang/reflect/Modifier.java
2020-07-17 15:54:13.192893982 -0700
@@ -32,7 +32,7 @@
* 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()
---
old/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java
2020-07-17 15:54:15.108893982 -0700
+++
new/src/java.base/share/classes/java/lang/reflect/ProxyGenerator.java
2020-07-17 15:54:14.428893982 -0700
@@ -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
--- old/src/java.base/share/classes/java/util/Properties.java 2020-07-17
15:54:16.376893982 -0700
+++ new/src/java.base/share/classes/java/util/Properties.java 2020-07-17
15:54:15.776893982 -0700
@@ -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.
On 7/17/2020 3:30 PM, Brian Burkhalter wrote:
> Hi Joe,
>
> +1
>
> Brian
>
>> On Jul 17, 2020, at 3:03 PM, Joe Darcy <joe.darcy at oracle.com
>> <mailto:joe.darcy at oracle.com>> wrote:
>>
>> Following-up on JDK-8237805 and some recent observations from Mikael
>> V., there are more locations in the base module where in-line @jls
>> and @jvms tags are appropriate to use. Please review their addition:
>>
>> http://cr.openjdk.java.net/~darcy/8249687.0/
>>
>> I checked that the sections were correct for the current JLS and
>> JVMS, which led to a change of referenced section in AssertionError.
>
More information about the core-libs-dev
mailing list