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

[Jonathan Gibbons]

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)
>       *
>