Index: tool/input_sdk/lib/core/iterator.dart |
diff --git a/tool/input_sdk/lib/core/iterator.dart b/tool/input_sdk/lib/core/iterator.dart |
index ed7aca9b67a1354b52659e6c7f3456ce0043c959..cd0ad320195b2f59f1ca53bc34f20f42ecb719fc 100644 |
--- a/tool/input_sdk/lib/core/iterator.dart |
+++ b/tool/input_sdk/lib/core/iterator.dart |
@@ -7,16 +7,17 @@ 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: |
* |
@@ -25,27 +26,37 @@ part of dart.core; |
* 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; |
} |