Better documentation on Sets and Maps, and more.

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 IterableBase<E> implements Set<E> {
   // Set.
   bool containsAll(Iterable<E> other) {
@@ skipping 38 matching lines @@
       retainSet = objectsToRetain;
     } else {
       retainSet = objectsToRetain.toSet();
     }
     retainWhere(retainSet.contains);
   }
 
   String toString() => ToString.iterableToString(this);
 }
 
+/**
+ * A [HashSet] is a hash-table based [Set] implementation.
+ *
+ * The elements of a `HashSet` must have consistent [Object.operator==]
+ * and [Object.hashCode] implementations. This means that the `==` operator
+ * must define a stable equivalence relation on the elements (reflexive,
+ * anti-symmetric, transitive, and consistent over time), and that `hashCode`
+ * must be the same for objects that are considered equal by `==`.
+ *
+ * The set allows `null` as an element.
+ *
+ * Most simple operations on `HashSet` are done in constant time: [add],
+ * [contains], [remove], and [length].
+ */
 class HashSet<E> extends _HashSetBase<E> {
   external HashSet();
 
   factory HashSet.from(Iterable<E> iterable) {
     return new HashSet<E>()..addAll(iterable);
   }
 
   // Iterable.
   external Iterator<E> get iterator;
 
   external int get length;
 
   external bool get isEmpty;
 
   external bool get isNotEmpty;
 
   external bool contains(Object object);
 
-  // Collection.
+  // Set.
   external void add(E element);
 
   external void addAll(Iterable<E> objects);
 
   external bool remove(Object object);
 
   external void removeAll(Iterable objectsToRemove);
 
   external void removeWhere(bool test(E element));
 
   external void retainWhere(bool test(E element));
 
   external void clear();
 
-  // Set.
   Set<E> _newSet() => new HashSet<E>();
 }