Upgrade Iterable and Iterator.

tool/input_sdk/lib/core/iterator.dart

 // Copyright (c) 2012, 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;
 
 /**
  * An interface for getting items, one at a time, from an object.
  *
- * The for-in construct transparently uses Iterator to test for the end
+ * The for-in construct transparently uses `Iterator` to test for the end
  * of the iteration, and to get each item (or _element_).
  *
  * If the object iterated over is changed during the iteration, the
  * behavior is unspecified.
  *
- * The Iterator is initially positioned before the first element. Before
- * accessing the first element the iterator must thus be advanced ([moveNext])
- * to point to the first element. If no element is left, then [moveNext]
- * returns false.
+ * The `Iterator` is initially positioned before the first element.
+ * Before accessing the first element the iterator must thus be advanced using
+ * [moveNext] to point to the first element.
+ * If no element is left, then [moveNext] returns false, [current]
+ * returns `null`, and all further calls to [moveNext] will also return false.
  *
  * A typical usage of an Iterator looks as follows:
  *
  *     var it = obj.iterator;
  *     while (it.moveNext()) {
  *       use(it.current);
  *     }
  *
- * **See also:** [Iteration]
- * (http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-iteration)
- * in the [library tour]
- * (http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
+ * **See also:**
+ * [Iteration](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#iteration)
+ * in the [library tour](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
  */
 abstract class Iterator<E> {
   /**
-   * Moves to the next element. Returns true if [current] contains the next
-   * element. Returns false, if no element was left.
+   * Moves to the next element.
+   *
+   * Returns true if [current] contains the next element.
+   * Returns false if no elements are left.
    *
    * It is safe to invoke [moveNext] even when the iterator is already
-   * positioned after the last element. In this case [moveNext] has no effect.
+   * positioned after the last element.
+   * In this case [moveNext] returns false again and has no effect.
+   *
+   * A call to `moveNext` may throw if iteration has been broken by
+   * changing the underlying collection.
    */
   bool moveNext();
 
   /**
    * Returns the current element.
    *
-   * Return [:null:] if the iterator has not yet been moved to the first
-   * element, or if the iterator has been moved after the last element of the
+   * Returns `null` if the iterator has not yet been moved to the first
+   * element, or if the iterator has been moved past the last element of the
    * [Iterable].
+   *
+   * The `current` getter should keep its value until the next call to
+   * [moveNext], even if an underlying collection changes.
+   * After a successful call to `moveNext`, the user doesn't need to cache
+   * the current value, but can keep reading it from the iterator.
    */
   E get current;
 }