8238239: java.lang.Record spec clarifications

Reviewed-by: psandoz

src/java.base/share/classes/java/lang/Record.java

@@ -109,7 +109,7 @@ public abstract class Record {
      * @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
+     * as this record, 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:
@@ -130,46 +130,70 @@ public abstract class Record {
      *
      * </ul>
      *
-     * The implicitly provided implementation conforms to the
+     * Apart from the semantics described above, the precise algorithm
-     * semantics described above; the implementation may or may not
+     * used in the implicitly provided implementation is unspecified
-     * accomplish this by using calls to the particular methods
+     * and is subject to change. The implementation may or may not use
-     * listed.
+     * calls to the particular methods listed, and may or may not
+     * perform comparisons in the order of component declaration.
      *
      * @see java.util.Objects#equals(Object,Object)
      *
      * @param   obj   the reference object with which to compare.
-     * @return  {@code true} if this object is equal to the
+     * @return  {@code true} if this record is equal to the
      *          argument; {@code false} otherwise.
      */
     @Override
     public abstract boolean equals(Object obj);
 
     /**
+     * Returns a hash code value for the record.
      * Obeys the general contract of {@link Object#hashCode Object.hashCode}.
+     * For records, hashing behavior is constrained by the refined contract
+     * of {@link Record#equals Record.equals}, so that any two records
+     * created from the same components must have the same hash code.
      *
      * @implSpec
      * The implicitly provided implementation returns a hash code value derived
-     * by combining the hash code value for all the components, according to
+     * by combining appropriate hashes from each component.
-     * {@link Object#hashCode()} for components whose types are reference types,
+     * The precise algorithm used in the implicitly provided implementation
-     * or the primitive wrapper hash code for components whose types are primitive
+     * is unspecified and is subject to change within the above limits.
-     * types.
+     * The resulting integer need not remain consistent from one
+     * execution of an application to another execution of the same
+     * application, even if the hashes of the component values were to
+     * remain consistent in this way.  Also, a component of primitive
+     * type may contribute its bits to the hash code differently than
+     * the {@code hashCode} of its primitive wrapper class.
      *
      * @see     Object#hashCode()
      *
-     * @return  a hash code value for this object.
+     * @return  a hash code value for this record.
      */
     @Override
     public abstract int hashCode();
 
     /**
-     * Obeys the general contract of {@link Object#toString Object.toString}.
+     * Returns a string representation of the record.
+     * In accordance with the general contract of {@link Object#toString()},
+     * the {@code toString} method returns a string that
+     * "textually represents" this record. The result should
+     * be a concise but informative representation that is easy for a
+     * person to read.
+     * <p>
+     * In addition to this general contract, record classes must further
+     * participate in the invariant that any two records which are
+     * {@linkplain Record#equals(Object) equal} must produce equal
+     * strings.  This invariant is necessarily relaxed in the rare
+     * case where corresponding equal component values might fail
+     * to produce equal strings for themselves.
      *
      * @implSpec
-     * The implicitly provided implementation returns a string that is derived
+     * The implicitly provided implementation returns a string which
-     * from the name of the record class and the names and string representations
+     * contains the name of the record class, the names of components
-     * of all the components, according to {@link Object#toString()} for components
+     * of the record, and string representations of component values,
-     * whose types are reference types, and the primitive wrapper {@code toString}
+     * so as to fulfill the contract of this method.
-     * method for components whose types are primitive types.
+     * The precise format produced by this implicitly provided implementation
+     * is subject to change, so the present syntax should not be parsed
+     * by applications to recover record component values.
      *
      * @see     Object#toString()
      *