Modernize the package's style.

lib/src/equality.dart

Index: lib/src/equality.dart
diff --git a/lib/equality.dart b/lib/src/equality.dart
similarity index 70%
copy from lib/equality.dart
copy to lib/src/equality.dart
index 5911863f75e11332a7303e96688786273e66ec9d..5a0d074bd8d70b630187ecf76cd2ce13d705683e 100644
--- a/lib/equality.dart
+++ b/lib/src/equality.dart
@@ -2,51 +2,36 @@
 // 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;
@@ -54,9 +39,7 @@ class DefaultEquality implements Equality {
   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);
@@ -64,11 +47,9 @@ class IdentityEquality implements Equality {
   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 =
@@ -106,15 +87,13 @@ class IterableEquality<E> implements Equality<Iterable<E>> {
   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()])
@@ -193,13 +172,11 @@ abstract class _UnorderedEquality<E, T extends Iterable<E>>
   }
 }
 
-/**
- * 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()])
@@ -208,16 +185,14 @@ class UnorderedIterableEquality<E> extends _UnorderedEquality<E, Iterable<E>> {
   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()])
@@ -226,12 +201,10 @@ class SetEquality<E> extends _UnorderedEquality<E, Set<E>> {
   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;
@@ -251,12 +224,10 @@ class _MapEntry {
   }
 }
 
-/**
- * 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;
@@ -301,22 +272,20 @@ class MapEquality<K, V> implements Equality<Map<K, V>> {
   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;
 
@@ -345,34 +314,30 @@ class MultiEquality<E> implements Equality<E> {
   }
 }
 
-/**
- * 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;