Update object.dart and some comments.

tool/input_sdk/lib/core/set.dart

 // Copyright (c) 2011, 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.core;
 
 /**
  * A collection of objects in which each object can occur only once.
  *
  * That is, for each object of the element type, the object is either considered
@@ skipping 13 matching lines @@
  *   uspecified,
  * * [LinkedHashSet] iterates in the insertion order of its elements, and
  * * a sorted set like [SplayTreeSet] iterates the elements in sorted order.
  *
  * It is generally not allowed to modify the set (add or remove elements) while
  * an operation on the set is being performed, for example during a call to
  * [forEach] or [containsAll]. Nor is it allowed to modify the set while
  * iterating either the set itself or any [Iterable] that is backed by the set,
  * such as the ones returned by methods like [where] and [map].
  */
-abstract class Set<E> extends IterableBase<E> implements EfficientLength {
+abstract class Set<E> extends Iterable<E> implements EfficientLength {
   /**
    * Creates an empty [Set].
    *
    * The created [Set] is a plain [LinkedHashSet].
    * As such, it considers elements that are equal (using [==]) to be
    * indistinguishable, and requires them to have a compatible
    * [Object.hashCode] implementation.
    *
    * The set is equivalent to one created by `new LinkedHashSet<E>()`.
    */
@@ skipping 36 matching lines @@
    * but must be consistent between changes to the set.
    */
   Iterator<E> get iterator;
 
   /**
    * Returns true if [value] is in the set.
    */
   bool contains(Object value);
 
   /**
-   * Adds [value] into the set. Returns `true` if [value] was added to the set.
+   * Adds [value] to the set.
    *
-   * If [value] already exists, the set is not changed and `false` is returned.
+   * Returns `true` if [value] (or an equal value) was not yet in the set.
+   * Otherwise returns `false` and the set is not changed.
+   *
+   * Example:
+   *
+   *     var set = new Set();
+   *     var time1 = new DateTime.fromMillisecondsSinceEpoch(0);
+   *     var time2 = new DateTime.fromMillisecondsSinceEpoch(0);
+   *     // time1 and time2 are equal, but not identical.
+   *     Expect.isTrue(time1 == time2);
+   *     Expect.isFalse(identical(time1, time2));
+   *     set.add(time1);  // => true.
+   *     // A value equal to time2 exists already in the set, and the call to
+   *     // add doesn't change the set.
+   *     set.add(time2);  // => false.
+   *     Expect.isTrue(set.length == 1);
+   *     Expect.isTrue(identical(time1, set.first));
    */
   bool add(E value);
 
   /**
    * Adds all [elements] to this Set.
    *
    * Equivalent to adding each element in [elements] using [add],
    * but some collections may be able to optimize it.
    */
   void addAll(Iterable<E> elements);
@@ skipping 75 matching lines @@
   /* Creates a [Set] with the same elements and behavior as this `Set`.
    *
    * The returned set behaves the same as this set
    * with regard to adding and removing elements.
    * It initially contains the same elements.
    * If this set specifies an ordering of the elements,
    * the returned set will have the same order.
    */
   Set<E> toSet();
 }