8367382: Expand use of representation equivalence terminology

Reviewed-by: rgiulietti

Author: jddarcy

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

@@ -1242,6 +1242,8 @@ public static int hashCode(double value) {
      * the same if and only if the method {@link
      * #doubleToLongBits(double)} returns the identical
      * {@code long} value when applied to each.
+     * In other words, {@linkplain ##repEquivalence representation
+     * equivalence} is used to compare the {@code double} values.
      *
      * @apiNote
      * This method is defined in terms of {@link
@@ -1455,6 +1457,12 @@ public int compareTo(Double anotherDouble) {
      *    Double.valueOf(d1).compareTo(Double.valueOf(d2))
      * </pre>
      *
+     * @apiNote
+     * One idiom to implement {@linkplain ##repEquivalence
+     * representation equivalence} on {@code double} values is
+     * {@snippet lang="java" :
+     * Double.compare(a, b) == 0
+     * }
      * @param   d1        the first {@code double} to compare
      * @param   d2        the second {@code double} to compare
      * @return  the value {@code 0} if {@code d1} is

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

@@ -871,6 +871,9 @@ public static int hashCode(float value) {
      * same if and only if the method {@link #floatToIntBits(float)}
      * returns the identical {@code int} value when applied to
      * each.
+     * In other words, {@linkplain Double##repEquivalence
+     * representation equivalence} is used to compare the {@code
+     * float} values.
      *
      * @apiNote
      * This method is defined in terms of {@link
@@ -1276,6 +1279,14 @@ public int compareTo(Float anotherFloat) {
      *    Float.valueOf(f1).compareTo(Float.valueOf(f2))
      * </pre>
      *
+     * @apiNote
+     * One idiom to implement {@linkplain
+     * Double##repEquivalence representation equivalence} on {@code
+     * float} values is
+     * {@snippet lang="java" :
+     * Float.compare(a, b) == 0
+     * }
+     *
      * @param   f1        the first {@code float} to compare.
      * @param   f2        the second {@code float} to compare.
      * @return  the value {@code 0} if {@code f1} is

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -127,7 +127,12 @@ protected Record() {}
      *
      * </ul>
      *
-     * Apart from the semantics described above, the precise algorithm
+     * Note that these rules imply that {@linkplain
+     * Double##repEquivalence representation equivalence} is used for
+     * the equality comparison of both primitive floating-point values
+     * and wrapped floating-point values.
+     *
+     * <p>Apart from the semantics described above, the precise algorithm
      * used in the implicitly provided implementation is unspecified
      * and is subject to change. The implementation may or may not use
      * calls to the particular methods listed, and may or may not