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.

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
+/// If the elements are maps, lists, sets, or other collections/composite objects,
-/// are maps, lists, sets, or other collections/composite objects, then the
+/// then the contents of those elements are not compared element by element unless their
-/// values 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
+/// If the elements are maps, lists, sets, or other collections/composite objects,
-/// are maps, lists, sets, or other collections/composite objects, then the
+/// then the contents of those elements are not compared element by element unless their
-/// values 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
+/// If the elements are maps, lists, sets, or other collections/composite objects,
-/// are maps, lists, sets, or other collections/composite objects, then the
+/// then the contents of those elements are not compared element by element unless their
-/// values 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:
 ///