From 9b8035d654cd4e36e79e1b8329f4457e0f3087f8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=89amonn=20McManus?= <emcmanus@google.com>
Date: Tue, 31 Oct 2023 12:08:54 -0700
Subject: [PATCH] Document why `EqualsTester.addEqualityGroup` has a
 `@Nullable` parameter.

RELNOTES=n/a
PiperOrigin-RevId: 578260904
---
 .../src/com/google/common/testing/EqualsTester.java    | 10 ++++++++++
 .../src/com/google/common/testing/EqualsTester.java    | 10 ++++++++++
 2 files changed, 20 insertions(+)

diff --git a/android/guava-testlib/src/com/google/common/testing/EqualsTester.java b/android/guava-testlib/src/com/google/common/testing/EqualsTester.java
index d4484702a994..5f02dba84855 100644
--- a/android/guava-testlib/src/com/google/common/testing/EqualsTester.java
+++ b/android/guava-testlib/src/com/google/common/testing/EqualsTester.java
@@ -95,6 +95,16 @@ public EqualsTester() {
   /**
    * Adds {@code equalityGroup} with objects that are supposed to be equal to each other and not
    * equal to any other equality groups added to this tester.
+   *
+   * <p>The {@code @Nullable} annotations on the {@code equalityGroup} parameter imply that the
+   * objects, and the array itself, can be null. That is for programmer convenience, when the
+   * objects come from factory methods that are themselves {@code @Nullable}. In reality neither the
+   * array nor its contents can be null, but it is not useful to force the use of {@code
+   * requireNonNull} or the like just to assert that.
+   *
+   * <p>{@code EqualsTester} will always check that every object it is given returns false from
+   * {@code equals(null)}, so it is neither useful nor allowed to include a null value in any
+   * equality group.
    */
   @CanIgnoreReturnValue
   public EqualsTester addEqualityGroup(@Nullable Object @Nullable ... equalityGroup) {
diff --git a/guava-testlib/src/com/google/common/testing/EqualsTester.java b/guava-testlib/src/com/google/common/testing/EqualsTester.java
index d4484702a994..5f02dba84855 100644
--- a/guava-testlib/src/com/google/common/testing/EqualsTester.java
+++ b/guava-testlib/src/com/google/common/testing/EqualsTester.java
@@ -95,6 +95,16 @@ public EqualsTester() {
   /**
    * Adds {@code equalityGroup} with objects that are supposed to be equal to each other and not
    * equal to any other equality groups added to this tester.
+   *
+   * <p>The {@code @Nullable} annotations on the {@code equalityGroup} parameter imply that the
+   * objects, and the array itself, can be null. That is for programmer convenience, when the
+   * objects come from factory methods that are themselves {@code @Nullable}. In reality neither the
+   * array nor its contents can be null, but it is not useful to force the use of {@code
+   * requireNonNull} or the like just to assert that.
+   *
+   * <p>{@code EqualsTester} will always check that every object it is given returns false from
+   * {@code equals(null)}, so it is neither useful nor allowed to include a null value in any
+   * equality group.
    */
   @CanIgnoreReturnValue
   public EqualsTester addEqualityGroup(@Nullable Object @Nullable ... equalityGroup) {