From 2a701b1e969f1da4cf01c234fed1f1daafa55348 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Wed, 11 Mar 2026 17:25:29 -0700
Subject: [PATCH] Document that ImmutableTable comparators affect ordering, not
 lookup

The orderRowsBy and orderColumnsBy methods on ImmutableTable.Builder
accept comparators that control iteration ordering, but row/column
lookups still use Object.equals. This was undocumented and surprising
to users (see #4010).

Add javadoc to both methods clarifying this distinction.
---
 .../google/common/collect/ImmutableTable.java    | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/guava/src/com/google/common/collect/ImmutableTable.java b/guava/src/com/google/common/collect/ImmutableTable.java
index 43b2b23b4d46..cc1b9bd45826 100644
--- a/guava/src/com/google/common/collect/ImmutableTable.java
+++ b/guava/src/com/google/common/collect/ImmutableTable.java
@@ -199,14 +199,26 @@ public static final class Builder<R, C, V> {
      */
     public Builder() {}
 
-    /** Specifies the ordering of the generated table's rows. */
+    /**
+     * Specifies the ordering of the generated table's rows.
+     *
+     * <p>The comparator is used only for ordering. Row lookups in the resulting table, including
+     * {@link ImmutableTable#row} and {@link ImmutableTable#rowMap}, still use {@link
+     * Object#equals}.
+     */
     @CanIgnoreReturnValue
     public Builder<R, C, V> orderRowsBy(Comparator<? super R> rowComparator) {
       this.rowComparator = checkNotNull(rowComparator, "rowComparator");
       return this;
     }
 
-    /** Specifies the ordering of the generated table's columns. */
+    /**
+     * Specifies the ordering of the generated table's columns.
+     *
+     * <p>The comparator is used only for ordering. Column lookups in the resulting table, including
+     * {@link ImmutableTable#column} and {@link ImmutableTable#columnMap}, still use {@link
+     * Object#equals}.
+     */
     @CanIgnoreReturnValue
     public Builder<R, C, V> orderColumnsBy(Comparator<? super C> columnComparator) {
       this.columnComparator = checkNotNull(columnComparator, "columnComparator");