JDK 16 RFR of JDK-8249687: Use inline @jls and @jvm tages in more places in java.base
Mandy Chung
mandy.chung at oracle.com
Fri Jul 17 23:56:08 UTC 2020
+1
Mandy
On 7/17/20 4:04 PM, Joe Darcy wrote:
> 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