From 28b4b84f37ecb08689183186e36946ce36872d65 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Krist=C3=B3f=20Horv=C3=A1th?=
 <51116212+KristofHorvath@users.noreply.github.com>
Date: Tue, 13 Jul 2021 19:24:06 +0200
Subject: [PATCH] Fix documentation of equality functions. (#84847)

The first line of the documentation of equality functions listEquals, mapEquals, and setEquals claimed that they are deep equality functions. A later paragraph explained that they check for deep equality only if the elements, which are collections, implement the equality operator to do so. That is almost never the case.

The first line of the documentation was changed to element-by-element equality, and a reference was added to the DeepCollectionEquality class.
---
 .../lib/src/foundation/collections.dart       | 24 +++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/flutter/lib/src/foundation/collections.dart b/packages/flutter/lib/src/foundation/collections.dart
index 44b0680ea8..71ef1a9ac1 100644
--- a/packages/flutter/lib/src/foundation/collections.dart
+++ b/packages/flutter/lib/src/foundation/collections.dart
@@ -4,16 +4,16 @@
 
 // TODO(ianh): These should be on the Set and List classes themselves.
 
-/// Compares two sets for deep equality.
+/// Compares two sets for element-by-element equality.
 ///
 /// Returns true if the sets are both null, or if they are both non-null, have
 /// the same length, and contain the same members. Returns false otherwise.
 /// Order is not compared.
 ///
-/// The term "deep" above refers to the first level of equality: if the elements
-/// are maps, lists, sets, or other collections/composite objects, then the
-/// values of those elements are not compared element by element unless their
+/// If the elements are maps, lists, sets, or other collections/composite objects,
+/// then the contents of those elements are not compared element by element unless their
 /// equality operators ([Object.==]) do so.
+/// For checking deep equality, consider using [DeepCollectionEquality] class.
 ///
 /// See also:
 ///
@@ -33,16 +33,16 @@ bool setEquals<T>(Set<T>? a, Set<T>? b) {
   return true;
 }
 
-/// Compares two lists for deep equality.
+/// Compares two lists for element-by-element equality.
 ///
 /// Returns true if the lists are both null, or if they are both non-null, have
 /// the same length, and contain the same members in the same order. Returns
 /// false otherwise.
 ///
-/// The term "deep" above refers to the first level of equality: if the elements
-/// are maps, lists, sets, or other collections/composite objects, then the
-/// values of those elements are not compared element by element unless their
+/// If the elements are maps, lists, sets, or other collections/composite objects,
+/// then the contents of those elements are not compared element by element unless their
 /// equality operators ([Object.==]) do so.
+/// For checking deep equality, consider using [DeepCollectionEquality] class.
 ///
 /// See also:
 ///
@@ -62,16 +62,16 @@ bool listEquals<T>(List<T>? a, List<T>? b) {
   return true;
 }
 
-/// Compares two maps for deep equality.
+/// Compares two maps for element-by-element equality.
 ///
 /// Returns true if the maps are both null, or if they are both non-null, have
 /// the same length, and contain the same keys associated with the same values.
 /// Returns false otherwise.
 ///
-/// The term "deep" above refers to the first level of equality: if the elements
-/// are maps, lists, sets, or other collections/composite objects, then the
-/// values of those elements are not compared element by element unless their
+/// If the elements are maps, lists, sets, or other collections/composite objects,
+/// then the contents of those elements are not compared element by element unless their
 /// equality operators ([Object.==]) do so.
+/// For checking deep equality, consider using [DeepCollectionEquality] class.
 ///
 /// See also:
 ///