Improve document for HashSet.

sdk/lib/collection/hash_set.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.
 
 part of dart.collection;
 
 /** Common parts of [HashSet] and [LinkedHashSet] implementations. */
 abstract class _HashSetBase<E> extends SetBase<E> {
 
   // The following two methods override the ones in SetBase.
@@ skipping 27 matching lines @@
  *
  * The elements of a `HashSet` must have consistent equality
  * and hashCode implementations. This means that the equals operation
  * must define a stable equivalence relation on the elements (reflexive,
  * symmetric, transitive, and consistent over time), and that the hashCode
  * must consistent with equality, so that the same for objects that are
  * considered equal.
  *
  * The set allows `null` as an element.
  *
- * Most simple operations on `HashSet` are done in (potentially amorteized)
+ * Most simple operations on `HashSet` are done in (potentially amortized)
  * constant time: [add], [contains], [remove], and [length], provided the hash
  * codes of objects are well distributed.
+ *
+ * The iteration order of the set is not specified and depends on
+ * the hashcodes of the provided elements. However, the order is stable:
+ * multiple iterations over the same set produce the same order, as long as
+ * the set is not modified.
  */
 abstract class HashSet<E> implements Set<E> {
   /**
    * Create a hash set using the provided [equals] as equality.
    *
    * 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 on some instances of E, the
    * [isValidKey] predicate can be used to restrict the keys that the functions
    * are applied to.
@@ skipping 40 matching lines @@
    * Effectively a shorthand for:
    *
    *     new HashSet<E>(equals: identical,
    *                    hashCode: identityHashCode)
    */
   external factory HashSet.identity();
 
   /**
    * Create a hash set containing all [elements].
    *
-   * Creates a hash set as by `new HashSet<E>()` and adds each element of
-   * `elements` to this set in the order they are iterated.
+   * Creates a hash set as by `new HashSet<E>()` and adds all given [elements]
+   * to the set. The elements are added in order. If [elements] contains
+   * two entries that are equal, but not identical, then the first one is
+   * the one in the resulting set.
    *
    * All the [elements] should be assignable to [E].
    * The `elements` iterable itself may have any element type, so this
    * constructor can be used to down-cast a `Set`, for example as:
    *
    *     Set<SuperType> superSet = ...;
    *     Set<SubType> subSet =
    *         new HashSet<SubType>.from(superSet.where((e) => e is SubType));
    */
   factory HashSet.from(Iterable elements) {
     HashSet<E> result = new HashSet<E>();
     for (final e in elements) {
       E element = e as Object/*=E*/;
       result.add(element);
     }
     return result;
   }
 
   /**
    * Provides an iterator that iterates over the elements of this set.
    *
    * The order of iteration is unspecified,
    * but consistent between changes to the set.
    */
   Iterator<E> get iterator;
 }