Better documentation on Sets and Maps, and more.

sdk/lib/core/set.dart

Index: sdk/lib/core/set.dart
diff --git a/sdk/lib/core/set.dart b/sdk/lib/core/set.dart
index ff8d4b3aac843b0619dcf97bb5c28ecc4bd11c6d..7b5980e06f91f65394ee81e675823bdf5c810edd 100644
--- a/sdk/lib/core/set.dart
+++ b/sdk/lib/core/set.dart
@@ -5,14 +5,37 @@
 part of dart.core;
 
 /**
- * This class is the public interface of a set. A set is a collection
- * without duplicates.
+ * A `Set` is a collection of elements where each element can occur only once.
+ *
+ * That is, for each object of the element type, the object is either considered
+ * to be in the set, or it is not in the set.
+ *
+ * Set implementations may consider some elements indistinguishable. These
+ * objects will be treated as being the same for any operation on the set.
+ *
+ * The default `Set` implementation, [HashSet], considers objects
+ * indistinguishable if they are equal with regard to [Object.operator==].
+ *
+ * Sets may be either ordered or unordered. [HashSet] is unordered and doesn't
+ * guarantee anything about the order that elements are accessed in by
+ * iteration. [LinkedHashSet] iterates in the insertion order of its elements.
  */
 abstract class Set<E> extends IterableBase<E> {
+  /**
+   * Creates an empty [Set].
+   *
+   * The created `Set` is a [HashSet]. As such, it considers elements that
+   * are equal (using `==`) to be undistinguishable, and requires them to
+   * have a compatible [Object.hashCode] implementation.
+   */
   factory Set() => new HashSet<E>();
 
   /**
    * Creates a [Set] that contains all elements of [other].
+   *
+   * The created `Set` is a [HashSet]. As such, it considers elements that
+   * are equal (using `==`) to be undistinguishable, and requires them to
+   * have a compatible [Object.hashCode] implementation.
    */
   factory Set.from(Iterable<E> other) => new HashSet<E>.from(other);
 
@@ -22,8 +45,9 @@ abstract class Set<E> extends IterableBase<E> {
   bool contains(E value);
 
   /**
-   * Adds [value] into the set. The method has no effect if
-   * [value] was already in the set.
+   * Adds [value] into the set.
+   *
+   * The method has no effect if [value] is already in the set.
    */
   void add(E value);
 
@@ -43,13 +67,12 @@ abstract class Set<E> extends IterableBase<E> {
   bool remove(Object value);
 
   /**
-   * Removes all of [elements] from this set.
+   * Removes each element of [elements] from this set.
    */
   void removeAll(Iterable elements);
 
   /**
-   * Removes all elements of this set that are not
-   * in [elements].
+   * Removes all elements of this set that are not elements in [elements].
    */
   void retainAll(Iterable elements);
 
@@ -64,22 +87,31 @@ abstract class Set<E> extends IterableBase<E> {
   void retainWhere(bool test(E element));
 
   /**
-   * Returns true if this Set contains all the elements of [other].
+   * Returns whether this Set contains all the elements of [other].
    */
   bool containsAll(Iterable<E> other);
 
   /**
    * Returns a new set which is the intersection between this set and [other].
+   *
+   * That is, the returned set contains all the elements of this `Set` that
+   * are also elements of [other].
    */
   Set<E> intersection(Set<E> other);
 
   /**
    * Returns a new set which contains all the elements of this set and [other].
+   *
+   * That is, the returned set contains all the elements of this `Set` and
+   * all the elements of [other].
    */
   Set<E> union(Set<E> other);
 
   /**
    * Returns a new set with the the elements of this that are not in [other].
+   *
+   * That is, the returned set contains all the elements of this `Set` that
+   * are not elements of [other].
    */
   Set<E> difference(Set<E> other);