From 58c9fbc93db6c27b00d1e53d7ee8bf6e382eea82 Mon Sep 17 00:00:00 2001
From: Joe Darcy <darcy@openjdk.org>
Date: Mon, 15 Sep 2025 16:22:35 +0000
Subject: [PATCH] 8367382: Expand use of representation equivalence terminology

Reviewed-by: rgiulietti
---
 src/java.base/share/classes/java/lang/Double.java |  8 ++++++++
 src/java.base/share/classes/java/lang/Float.java  | 11 +++++++++++
 src/java.base/share/classes/java/lang/Record.java |  9 +++++++--
 3 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/Double.java b/src/java.base/share/classes/java/lang/Double.java
index 5ab6dce080b..c43ec054661 100644
--- a/src/java.base/share/classes/java/lang/Double.java
+++ b/src/java.base/share/classes/java/lang/Double.java
@@ -1242,6 +1242,8 @@ public final class Double extends Number
      * 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 final class Double extends Number
      *    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
diff --git a/src/java.base/share/classes/java/lang/Float.java b/src/java.base/share/classes/java/lang/Float.java
index 4344d9657b4..3ee4f4ce619 100644
--- a/src/java.base/share/classes/java/lang/Float.java
+++ b/src/java.base/share/classes/java/lang/Float.java
@@ -871,6 +871,9 @@ public final class Float extends Number
      * 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 final class Float extends Number
      *    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
diff --git a/src/java.base/share/classes/java/lang/Record.java b/src/java.base/share/classes/java/lang/Record.java
index 808bc7cc9cd..f15ee07a964 100644
--- a/src/java.base/share/classes/java/lang/Record.java
+++ b/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 @@ public abstract class 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