Improve document for HashSet.

sdk/lib/collection/hash_set.dart

Index: sdk/lib/collection/hash_set.dart
diff --git a/sdk/lib/collection/hash_set.dart b/sdk/lib/collection/hash_set.dart
index 89558f827a43824870273f91c9ffaefd09ac0a1c..49c22583402f175bc9ce22f47016453aed27eb0b 100644
--- a/sdk/lib/collection/hash_set.dart
+++ b/sdk/lib/collection/hash_set.dart
@@ -108,8 +108,15 @@ abstract class HashSet<E> implements Set<E> {
   /**
    * 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.

[Lasse Reichstein Nielsen, 2016/12/13 14:01:33]

Good idea.

[floitsch, 2016/12/13 14:08:31]

Acknowledged.

+   *
+   * The iteration order of the resulting set is undetermined and depends on

[Lasse Reichstein Nielsen, 2016/12/13 14:01:33]

I don't think we have used "undetermined" anywhere before. Maybe "implementation
dependent" or just "not specified' or "not guaranteed".

[floitsch, 2016/12/13 14:08:31]

not specified.

+   * 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.

[Lasse Reichstein Nielsen, 2016/12/13 14:01:33]

I'm not sure we need to repeat what unordered set means in every constructor.
That said, it's not really *repeating* since we haven't spelled it out anywhere.
How about moving this paragraph to the class description instead of here?

[floitsch, 2016/12/13 14:08:31]

Done.

    *
    * All the [elements] should be assignable to [E].
    * The `elements` iterable itself may have any element type, so this