Better documentation on Sets and Maps, and more.

sdk/lib/collection/linked_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;
 
+/**
+ * A [LinkedHashSet] is a hash-table based [Set] implementation.
+ *
+ * The `LinkedHashSet` also keep track of the order that elements were inserted

[ngeoffray, 2013/06/04 11:51:33]

keep -> keeps

+ * in, and iteration happens in first-to-last insertion order.
+ *
+ * The elements of a `LinkedHashSet` 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, trasitive, and consistent over time), and that `hashCode`

[ngeoffray, 2013/06/04 11:51:33]

trasitive -> transitive

+ * 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 LinkedHashSet<E> extends _HashSetBase<E> {
 
   external LinkedHashSet();
 
   factory LinkedHashSet.from(Iterable<E> iterable) {
     return new LinkedHashSet<E>()..addAll(iterable);
   }
 
   // Iterable.
+
+  /** Return an iterator that iterates over elements in insertion order. */
   external Iterator<E> get iterator;
 
   external int get length;
 
   external bool get isEmpty;
 
   external bool get isNotEmpty;
 
   external bool contains(Object object);
 
+  /** Perform an operation on each element in insertion order. */
   external void forEach(void action(E element));
 
   external E get first;
 
   external E get last;
 
   E get single {
     if (length == 1) return first;
     var message = (length == 0) ? "No Elements" : "Too many elements";
     throw new StateError(message);
@@ skipping 10 matching lines @@
 
   external void removeWhere(bool test(E element));
 
   external void retainWhere(bool test(E element));
 
   external void clear();
 
   // Set.
   Set<E> _newSet() => new LinkedHashSet<E>();
 }