JDK 14 RFR of JDK-8234783: Improve wording of spec of Record.equals

[Joe Darcy]

Hi Jon,

Thanks for the comments; second take on the re-wording up at

     http://cr.openjdk.java.net/~darcy/8234783.1/

and copied below for convenience.

Cheers,

-Joe

--- old/src/java.base/share/classes/java/lang/Record.java 2020-01-06 
16:18:43.505405539 -0800
+++ new/src/java.base/share/classes/java/lang/Record.java 2020-01-06 
16:18:43.317311546 -0800
@@ -92,8 +92,8 @@
  public abstract class Record {
      /**
       * Indicates whether some other object is "equal to" this one.  In 
addition
-     * to the general contract of {@link Object#equals(Object)},
-     * record classes must further participate in the invariant that when
+     * to the general contract of {@link Object#equals(Object) 
Object.equals},
+     * record classes must further obey the invariant that when
       * a record instance is "copied" by passing the result of the 
record component
       * accessor methods to the canonical constructor, as follows:
       * <pre>
@@ -102,17 +102,37 @@
       * then it must be the case that {@code r.equals(copy)}.
       *
       * @implSpec
-     * The implicitly provided implementation returns {@code true} if and
-     * only if the argument is an instance of the same record type as 
this object,
-     * and each component of this record is equal to the corresponding 
component
-     * of the argument, according to {@link 
java.util.Objects#equals(Object,Object)}
-     * for components whose types are reference types, and according to 
the semantics
-     * of the {@code equals} method on the corresponding primitive 
wrapper type.
+     * The implicitly provided implementation returns {@code true} if
+     * and only if the argument is an instance of the same record type
+     * as this object, and each component of this record is equal to
+     * the corresponding component of the argument; otherwise, {@code
+     * false} is returned. Equality of a component {@code c} is
+     * determined as follows:
+     * <ul>
+     *
+     * <li> If the component is of a reference type, the component is
+     * considered equal if and only if {@link
+     * java.util.Objects#equals(Object,Object)
+     * Objects.equals(this.c(), r.c()} would return {@code true}.
+     *
+     * <li> If the component is of a primitive type, using the
+     * corresponding primitive wrapper class {@code PW} (the wrapper
+     * class {@code java.lang.Integer} for {@code int}, and so on) the
+     * component is considered equal if and only if {@code
+     * PW.valueOf(this.c()).equals(PW.valueOf(r.c()))} would return
+     * {@code true}.
+     *
+     * </ul>
+     *
+     * The implicitly provided implementation conforms to the
+     * semantics described above; the implementation may or may not
+     * accomplish this by using calls to the particular methods
+     * listed.
       *
       * @see java.util.Objects#equals(Object,Object)
       *
       * @param   obj   the reference object with which to compare.
-     * @return  {@code true} if this object is the same as the obj
+     * @return  {@code true} if this object is equal to the
       *          argument; {@code false} otherwise.
       */
      @Override

On 1/6/2020 1:22 PM, Jonathan Gibbons wrote:
> I like what you're trying to do, but the wording used to introduce the 
> names `cr` and `cp` feels a bit contorted.  How about using a single 
> name, c, introduced up front in this line:
>
>
> +     * of the argument. Equality of a component {@code c} is 
> determined as follows:
>
> with the rest of the text updated accordingly. Note the use of the 
> indefinite article `a component` when the name is introduced, and the 
> definite article `the component` in subsequent references.
>
> -- Jon
>
>
> On 1/6/20 1:08 PM, Joe Darcy wrote:
>> Hello,
>>
>> Please review a clarification to the specification of Record.equals:
>>
>>     JDK-8234783: Improve wording of spec of Record.equals
>>     http://cr.openjdk.java.net/~darcy/8234783.0/
>>
>> Patch below.
>>
>> Thanks,
>>
>> -Joe
>>
>> --- old/src/java.base/share/classes/java/lang/Record.java 2020-01-06 
>> 13:00:52.179585999 -0800
>> +++ new/src/java.base/share/classes/java/lang/Record.java 2020-01-06 
>> 13:00:51.987681999 -0800
>> @@ -105,9 +105,21 @@
>>       * The implicitly provided implementation returns {@code true} 
>> if and
>>       * only if the argument is an instance of the same record type 
>> as this object,
>>       * and each component of this record is equal to the 
>> corresponding component
>> -     * of the argument, according to {@link 
>> java.util.Objects#equals(Object,Object)}
>> -     * for components whose types are reference types, and according 
>> to the semantics
>> -     * of the {@code equals} method on the corresponding primitive 
>> wrapper type.
>> +     * of the argument. Equality of the components is determined as 
>> follows:
>> +     * <ul>
>> +     *
>> +     * <li> If the component is of a reference type, the component 
>> {@code
>> +     * cr} is considered equal if and only if {@link
>> +     * java.util.Objects#equals(Object,Object)
>> +     * Objects.equals(this.cr(), r.cr()} would return true .
>> +     *
>> +     * <li> If the component is of a primitive type, using the
>> +     * corresponding primitive wrapper class {@code P} the component
>> +     * {@code cp} is considered equal if and only if {@code
>> +     * P.valueOf(this.cp()).equals(P.valueOf(r.cp()))} would return
>> +     * true.
>> +     *
>> +     * </ul>
>>       *
>>       * @see java.util.Objects#equals(Object,Object)
>>       *
>>