Update {,Linked}Hash{Set,Map} documentation.

sdk/lib/collection/linked_hash_set.dart

Index: sdk/lib/collection/linked_hash_set.dart
diff --git a/sdk/lib/collection/linked_hash_set.dart b/sdk/lib/collection/linked_hash_set.dart
index b937e53c0de3f22e82e84af7d9c7a749be5e0563..a4848f46693759f5d9c803d5e157d5b8d0c564ca 100644
--- a/sdk/lib/collection/linked_hash_set.dart
+++ b/sdk/lib/collection/linked_hash_set.dart
@@ -36,32 +36,55 @@ abstract class LinkedHashSet<E> implements HashSet<E> {
    *
    * The provided [equals] must define a stable equivalence relation, and
    * [hashCode] must be consistent with [equals]. If the [equals] or [hashCode]
-   * methods won't work on all objects, but only to instances of E, the
-   * [isValidKey] predicate can be used to restrict the keys that they are
-   * applied to. Any key for which [isValidKey] returns false is automatically
-   * assumed to not be in the set.
+   * methods won't work on all objects, but only on some instances of E, the
+   * [isValidKey] predicate can be used to restrict the keys that the functions
+   * are applied to.
+   * Any key for which [isValidKey] returns false is automatically assumed
+   * to not be in the set when asking `contains`.
    *
    * If [equals] or [hashCode] are omitted, the set uses
-   * the objects' intrinsic [Object.operator==] and [Object.hashCode],
-   *
-   * If [isValidKey] is omitted, it defaults to testing if the object is an
-   * [E] instance.
+   * the elements' intrinsic [Object.operator==] and [Object.hashCode],
+   * and [isValidKey] is ignored since these operations are assumed
+   * to work on all objects.
    *
    * If you supply one of [equals] and [hashCode],
    * you should generally also to supply the other.
-   * An example would be using [identical] and [identityHashCode],
-   * which is equivalent to using the shorthand [LinkedSet.identity]).
+   *
+   * If the supplied `equals` or `hashCode` functions won't work on all [E]
+   * objects, and the map will be used in a setting where a non-`E` object
+   * is passed to, e.g., `contains`, then the [isValidKey] function should
+   * also be supplied.
+   *
+   * If [isValidKey] is omitted, it defaults to testing if the object is an
+   * [E] instance. That means that:
+   *
+   *     new LinkedHashSet<int>(equals: (int e1, int e2) => (e1 - e2) % 5 == 0,
+   *                            hashCode: (int e) => e % 5)
+   *
+   * does not need an `isValidKey` argument, because it defaults to only
+   * accepting `int` values which are accepted by both `equals` and `hashCode`.
+   *
+   * If neither `equals`, `hashCode`, nor `isValidKey` is provided,
+   * the default `isValidKey` instead accepts all values.
+   * The default equality and hashcode operations are assumed to work on all
+   * objects.
+   *
+   * Likewise, if `equals` is [identical], `hashCode` is [identityHashCode]
+   * and `isValidKey` is omitted, the resulting set is identity based,
+   * and the `isValidKey` defaults to accepting all keys.
+   * Such a map can be created directly using [LinkedHashSet.identity].
    */
-  external factory LinkedHashSet({ bool equals(E e1, E e2),
-                                   int hashCode(E e),
-                                   bool isValidKey(potentialKey) });
+  external factory LinkedHashSet({bool equals(E e1, E e2),
+                                  int hashCode(E e),
+                                  bool isValidKey(potentialKey)});
 
   /**
    * Creates an insertion-ordered identity-based set.
    *
    * Effectively a shorthand for:
    *
-   *     new LinkedHashSet(equals: identical, hashCode: identityHashCodeOf)
+   *     new LinkedHashSet(equals: identical,
+   *                       hashCode: identityHashCodeOf)
    */
   external factory LinkedHashSet.identity();