test: add unit tests for custom equals functionality in observable collections

Author: amondnet

mobx/lib/src/api/observable_collections/observable_list.dart

@@ -10,6 +10,34 @@ Atom _observableListAtom<T>(ReactiveContext? context, String? name) {
 ///
 /// As the name suggests, this is the Observable-counterpart to the standard Dart `List<T>`.
 ///
+/// ## Custom Equality
+///
+/// You can provide a custom `equals` parameter to control when values are considered
+/// equal. This is useful for optimizing change detection or implementing custom
+/// equality semantics:
+///
+/// ```dart
+/// // Only notify changes when names are different
+/// final list = ObservableList<Person>(
+///   equals: (a, b) => a?.name == b?.name
+/// );
+///
+/// // Deep equality for nested structures
+/// final list = ObservableList<List<int>>(
+///   equals: (a, b) {
+///     if (a == null && b == null) return true;
+///     if (a == null || b == null) return false;
+///     return a.length == b.length &&
+///       a.asMap().entries.every((e) => e.value == b[e.key]);
+///   }
+/// );
+/// ```
+///
+/// Note: Bulk operations like `replaceRange` and `setRange` always trigger
+/// notifications for performance reasons, regardless of the custom equals function.
+///
+/// ## Basic Usage
+///
 /// ```dart
 /// final list = ObservableList<int>.of([1]);
 ///

mobx/lib/src/api/observable_collections/observable_map.dart

@@ -10,6 +10,24 @@ Atom _observableMapAtom<K, V>(ReactiveContext? context, String? name) {
 ///
 /// As the name suggests, this is the Observable-counterpart to the standard Dart `Map<K,V>`.
 ///
+/// ## Custom Equality for Values
+///
+/// You can provide a custom `equals` parameter to control when values are considered
+/// equal. This only affects value comparisons - keys are always compared using standard
+/// equality:
+///
+/// ```dart
+/// // Only notify changes when person names are different
+/// final map = ObservableMap<String, Person>(
+///   equals: (a, b) => a?.name == b?.name
+/// );
+///
+/// map['key'] = Person('Alice', 25);
+/// map['key'] = Person('Alice', 30); // No notification - same name
+/// ```
+///
+/// ## Basic Usage
+///
 /// ```dart
 /// final map = ObservableMap<String, int>.of({'first': 1});
 ///

mobx/lib/src/api/observable_collections/observable_set.dart

@@ -5,6 +5,27 @@ Atom _observableSetAtom<T>(ReactiveContext context, String? name) =>
 
 /// ObservableSet provides a reactive set that notifies changes when a member is added or removed.
 ///
+/// ## Custom Equality
+///
+/// You can provide a custom `equals` parameter to determine set membership.
+/// This is particularly useful when you need custom equality semantics:
+///
+/// ```dart
+/// // Case-insensitive string set
+/// final set = ObservableSet<String>(
+///   equals: (a, b) => a?.toLowerCase() == b?.toLowerCase()
+/// );
+///
+/// set.add('Hello');
+/// set.add('HELLO'); // Won't be added - considered equal
+/// set.contains('hello'); // Returns true
+/// ```
+///
+/// When using custom equals, the set behaves consistently across all operations
+/// including `add`, `contains`, `remove`, and `lookup`.
+///
+/// ## Basic Usage
+///
 /// ```dart
 /// final set = ObservableSet.of([1, 2, 3]);
 ///