Modernize the package's style.

lib/src/equality.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/**
- * Defines equality relations on collections.
- */
-library dart.pkg.collection.equality;
-
 import "dart:collection";
 
 const int _HASH_MASK = 0x7fffffff;
 
-/**
- * A generic equality relation on objects.
- */
+/// A generic equality relation on objects.
 abstract class Equality<E> {
   const factory Equality() = DefaultEquality;
 
-  /**
-   * Compare two elements for being equal.
-   *
-   * This should be a proper equality relation.
-   */
+  /// Compare two elements for being equal.
+  ///
+  /// This should be a proper equality relation.
   bool equals(E e1, E e2);
 
-  /**
-   * Get a hashcode of an element.
-   *
-   * The hashcode should be compatible with [equals], so that if
-   * `equals(a, b)` then `hash(a) == hash(b)`.
-   */
+  /// Get a hashcode of an element.
+  ///
+  /// The hashcode should be compatible with [equals], so that if
+  /// `equals(a, b)` then `hash(a) == hash(b)`.
   int hash(E e);
 
-  /**
-   * Test whether an object is a valid argument to [equals] and [hash].
-   *
-   * Some implementations may be restricted to only work on specific types
-   * of objects.
-   */
+  /// Test whether an object is a valid argument to [equals] and [hash].
+  ///
+  /// Some implementations may be restricted to only work on specific types
+  /// of objects.
   bool isValidKey(Object o);
 }
 
-/**
- * Equality of objects that compares only the natural equality of the objects.
- *
- * This equality uses the objects' own [Object.==] and [Object.hashCode] for
- * the equality.
- */
+/// Equality of objects that compares only the natural equality of the objects.
+///
+/// This equality uses the objects' own [Object.==] and [Object.hashCode] for
+/// the equality.
 class DefaultEquality implements Equality {
   const DefaultEquality();
   bool equals(Object e1, Object e2) => e1 == e2;
   int hash(Object e) => e.hashCode;
   bool isValidKey(Object o) => true;
 }
 
-/**
- * Equality of objects that compares only the identity of the objects.
- */
+/// Equality of objects that compares only the identity of the objects.
 class IdentityEquality implements Equality {
   const IdentityEquality();
   bool equals(Object e1, Object e2) => identical(e1, e2);
   int hash(Object e) => identityHashCode(e);
   bool isValidKey(Object o) => true;
 }
 
-/**
- * Equality on iterables.
- *
- * Two iterables are equal if they have the same elements in the same order.
- */
+/// Equality on iterables.
+///
+/// Two iterables are equal if they have the same elements in the same order.
 class IterableEquality<E> implements Equality<Iterable<E>> {
   final Equality<E> _elementEquality;
   const IterableEquality([Equality<E> elementEquality =
                               const DefaultEquality()])
       : _elementEquality = elementEquality;
 
   bool equals(Iterable<E> elements1, Iterable<E> elements2) {
     if (identical(elements1, elements2)) return true;
     if (elements1 == null || elements2 == null) return false;
     Iterator it1 = elements1.iterator;
@@ skipping 17 matching lines @@
     }
     hash = (hash + (hash << 3)) & _HASH_MASK;
     hash ^= (hash >> 11);
     hash = (hash + (hash << 15)) & _HASH_MASK;
     return hash;
   }
 
   bool isValidKey(Object o) => o is Iterable<E>;
 }
 
-/**
- * Equality on lists.
- *
- * Two lists are equal if they have the same length and their elements
- * at each index are equal.
- *
- * This is effectively the same as [IterableEquality] except that it
- * accesses elements by index instead of through iteration.
- */
+/// Equality on lists.
+///
+/// Two lists are equal if they have the same length and their elements
+/// at each index are equal.
+///
+/// This is effectively the same as [IterableEquality] except that it
+/// accesses elements by index instead of through iteration.
 class ListEquality<E> implements Equality<List<E>> {
   final Equality<E> _elementEquality;
   const ListEquality([Equality<E> elementEquality = const DefaultEquality()])
       : _elementEquality = elementEquality;
 
   bool equals(List<E> e1, List<E> e2) {
     if (identical(e1, e2)) return true;
     if (e1 == null || e2 == null) return false;
     int length = e1.length;
     if (length != e2.length) return false;
@@ skipping 58 matching lines @@
       int c = _elementEquality.hash(element);
       hash = (hash + c) & _HASH_MASK;
     }
     hash = (hash + (hash << 3)) & _HASH_MASK;
     hash ^= (hash >> 11);
     hash = (hash + (hash << 15)) & _HASH_MASK;
     return hash;
   }
 }
 
-/**
- * Equality of the elements of two iterables without considering order.
- *
- * Two iterables are considered equal if they have the same number of elements,
- * and the elements of one set can be paired with the elements
- * of the other iterable, so that each pair are equal.
- */
+/// Equality of the elements of two iterables without considering order.
+///
+/// Two iterables are considered equal if they have the same number of elements,
+/// and the elements of one set can be paired with the elements
+/// of the other iterable, so that each pair are equal.
 class UnorderedIterableEquality<E> extends _UnorderedEquality<E, Iterable<E>> {
   const UnorderedIterableEquality(
       [Equality<E> elementEquality = const DefaultEquality()])
       : super(elementEquality);
 
   bool isValidKey(Object o) => o is Iterable<E>;
 }
 
-/**
- * Equality of sets.
- *
- * Two sets are considered equal if they have the same number of elements,
- * and the elements of one set can be paired with the elements
- * of the other set, so that each pair are equal.
- *
- * This equality behaves the same as [UnorderedIterableEquality] except that
- * it expects sets instead of iterables as arguments.
- */
+/// Equality of sets.
+///
+/// Two sets are considered equal if they have the same number of elements,
+/// and the elements of one set can be paired with the elements
+/// of the other set, so that each pair are equal.
+///
+/// This equality behaves the same as [UnorderedIterableEquality] except that
+/// it expects sets instead of iterables as arguments.
 class SetEquality<E> extends _UnorderedEquality<E, Set<E>> {
   const SetEquality(
       [Equality<E> elementEquality = const DefaultEquality()])
       : super(elementEquality);
 
   bool isValidKey(Object o) => o is Set<E>;
 }
 
-/**
- *  Internal class used by [MapEquality].
- *
- *  The class represents a map entry as a single object,
- *  using a combined hashCode and equality of the key and value.
- */
+/// Internal class used by [MapEquality].
+///
+/// The class represents a map entry as a single object,
+/// using a combined hashCode and equality of the key and value.
 class _MapEntry {
   final MapEquality equality;
   final key;
   final value;
   _MapEntry(this.equality, this.key, this.value);
 
   int get hashCode =>
       (3 * equality._keyEquality.hash(key) +
        7 * equality._valueEquality.hash(value)) & _HASH_MASK;
 
   bool operator==(Object other) {
     if (other is! _MapEntry) return false;
     _MapEntry otherEntry = other;
     return equality._keyEquality.equals(key, otherEntry.key) &&
            equality._valueEquality.equals(value, otherEntry.value);
 
   }
 }
 
-/**
- * Equality on maps.
- *
- * Two maps are equal if they have the same number of entries, and if the
- * entries of the two maps are pairwise equal on both key and value.
- */
+/// Equality on maps.
+///
+/// Two maps are equal if they have the same number of entries, and if the
+/// entries of the two maps are pairwise equal on both key and value.
 class MapEquality<K, V> implements Equality<Map<K, V>> {
   final Equality<K> _keyEquality;
   final Equality<V> _valueEquality;
   const MapEquality({ Equality<K> keys : const DefaultEquality(),
                       Equality<V> values : const DefaultEquality() })
       : _keyEquality = keys, _valueEquality = values;
 
   bool equals(Map<K, V> e1, Map<K, V> e2) {
     if (identical(e1, e2)) return true;
     if (e1 == null || e2 == null) return false;
@@ skipping 24 matching lines @@
     }
     hash = (hash + (hash << 3)) & _HASH_MASK;
     hash ^= (hash >> 11);
     hash = (hash + (hash << 15)) & _HASH_MASK;
     return hash;
   }
 
   bool isValidKey(Object o) => o is Map<K, V>;
 }
 
-/**
- * Combines several equalities into a single equality.
- *
- * Tries each equality in order, using [Equality.isValidKey], and returns
- * the result of the first equality that applies to the argument or arguments.
- *
- * For `equals`, the first equality that matches the first argument is used,
- * and if the second argument of `equals` is not valid for that equality,
- * it returns false.
- *
- * Because the equalities are tried in order, they should generally work on
- * disjoint types. Otherwise the multi-equality may give inconsistent results
- * for `equals(e1, e2)` and `equals(e2, e1)`. This can happen if one equality
- * considers only `e1` a valid key, and not `e2`, but an equality which is
- * checked later, allows both.
- */
+/// Combines several equalities into a single equality.
+///
+/// Tries each equality in order, using [Equality.isValidKey], and returns
+/// the result of the first equality that applies to the argument or arguments.
+///
+/// For `equals`, the first equality that matches the first argument is used,
+/// and if the second argument of `equals` is not valid for that equality,
+/// it returns false.
+///
+/// Because the equalities are tried in order, they should generally work on
+/// disjoint types. Otherwise the multi-equality may give inconsistent results
+/// for `equals(e1, e2)` and `equals(e2, e1)`. This can happen if one equality
+/// considers only `e1` a valid key, and not `e2`, but an equality which is
+/// checked later, allows both.
 class MultiEquality<E> implements Equality<E> {
   final Iterable<Equality<E>> _equalities;
 
   const MultiEquality(Iterable<Equality<E>> equalities)
       : _equalities = equalities;
 
   bool equals(E e1, E e2) {
     for (Equality<E> eq in _equalities) {
       if (eq.isValidKey(e1)) return eq.isValidKey(e2) && eq.equals(e1, e2);
     }
     return false;
   }
 
   int hash(E e) {
     for (Equality<E> eq in _equalities) {
       if (eq.isValidKey(e)) return eq.hash(e);
     }
     return -1;
   }
 
   bool isValidKey(Object o) {
     for (Equality<E> eq in _equalities) {
       if (eq.isValidKey(o)) return true;
     }
     return false;
   }
 }
 
-/**
- * Deep equality on collections.
- *
- * Recognizes lists, sets, iterables and maps and compares their elements using
- * deep equality as well.
- *
- * Non-iterable/map objects are compared using a configurable base equality.
- *
- * Works in one of two modes: ordered or unordered.
- *
- * In ordered mode, lists and iterables are required to have equal elements
- * in the same order. In unordered mode, the order of elements in iterables
- * and lists are not important.
- *
- * A list is only equal to another list, likewise for sets and maps. All other
- * iterables are compared as iterables only.
- */
+/// Deep equality on collections.
+///
+/// Recognizes lists, sets, iterables and maps and compares their elements using
+/// deep equality as well.
+///
+/// Non-iterable/map objects are compared using a configurable base equality.
+///
+/// Works in one of two modes: ordered or unordered.
+///
+/// In ordered mode, lists and iterables are required to have equal elements
+/// in the same order. In unordered mode, the order of elements in iterables
+/// and lists are not important.
+///
+/// A list is only equal to another list, likewise for sets and maps. All other
+/// iterables are compared as iterables only.
 class DeepCollectionEquality implements Equality {
   final Equality _base;
   final bool _unordered;
   const DeepCollectionEquality([Equality base = const DefaultEquality()])
       : _base = base, _unordered = false;
 
-  /**
-   * Creates a deep equality on collections where the order of lists and
-   * iterables are not considered important. That is, lists and iterables are
-   * treated as unordered iterables.
-   */
+  /// Creates a deep equality on collections where the order of lists and
+  /// iterables are not considered important. That is, lists and iterables are
+  /// treated as unordered iterables.
   const DeepCollectionEquality.unordered(
       [Equality base = const DefaultEquality()])
       : _base = base, _unordered = true;
 
   bool equals(e1, e2) {
     if (e1 is Set) {
       if (e2 is! Set) return false;
       return new SetEquality(this).equals(e1, e2);
     }
     if (e1 is Map) {
@@ skipping 24 matching lines @@
       if (o is List) return new ListEquality(this).hash(o);
       if (o is Iterable) return new IterableEquality(this).hash(o);
     } else if (o is Iterable) {
       return new UnorderedIterableEquality(this).hash(o);
     }
     return _base.hash(o);
   }
 
   bool isValidKey(Object o) => o is Iterable || o is Map || _base.isValidKey(o);
 }