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

[Jonathan Gibbons]

Looks good to me.

-- Jon


On 01/06/2020 04:23 PM, Joe Darcy wrote:
> 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)
>>>       *
>>>