Clarify behavior of iterables and iterators with sync*.

docs/language/dartLangSpec.tex

Index: docs/language/dartLangSpec.tex
===================================================================
--- docs/language/dartLangSpec.tex	(revision 42940)
+++ docs/language/dartLangSpec.tex	(working copy)
@@ -3505,13 +3505,39 @@
 }
 
 \LMHash{}
-If $f$ is marked \SYNC* (\ref{functions}), then a fresh instance $i$ implementing the built-in class \code{Iterable} is associated with the invocation and immediately returned. When iteration over the iterable is started, by getting an iterator $j$ from the iterable and calling \code{moveNext()} on it, execution of the body of $f$ will begin. When $f$ terminates, $j$ is positioned after its last element, so that its current value is \NULL{} and the current call to \code{moveNext()} on $j$ returns false, as will all further calls.
+If $f$ is marked \SYNC* (\ref{functions}), then a fresh instance $i$ implementing the built-in class \code{Iterable} is associated with the invocation and immediately returned. The behavior of the \code{Iterable}  must be compatible with the \code{IterableBase} class in the \code{dart:core} library. 

[Lasse Reichstein Nielsen, 2015/01/22 15:23:45]

Still doesn't *really* say anything (it's unspecified what it means to be
"compatible" with a class). I think I know what it means - that the members
other than "iterator" must behave in the same way depending on the iterator
getter as the methods in IterableBase behaves depending on their iterator getter
- but we can't expect all readers to read it that way.

And it again just means that they must behave as specified by Iterable, because
IterableBase gets its documentation from Iterable, and the only promises made by
IterableBase are the documented behavior, not the actual implementation
(although there shouldn't be any way to differ).

If Iterable's documentation isn't sufficient, we should fix that, not bake an
implementation helper class into the specification. I'll try adding some more
precise documentation to Iterable.

 
-% Can we get more than one iterator from this Iterable? I'd say yes. And if so, do they restart the computation or do they iterate over previously computed results. My guess is the latter.
-% I also assume we extend the IterableBase implementation; otherwise one can pre-compute
-% it all
+\commentary{
+A Dart implementation will need to provide a specific implementation of \code{Iterable} that will be returned by \SYNC* methods. The only method that needs to be added by the Dart implementation is \code{iterator}.  In all other respects, the behavior of the \code{Iterable} is dictated by the use of \code{IterableBase}.
+}
 
+\rationale{
+Ideally, it would suffice to state that an implementation of \code{utterable} must be provided, and we would not refer to a specific implementation. However, the contract for \code{Iterable} is not as precise as we would like.
+}
+
+
 \LMHash{}
+When iteration over the iterable is started, by getting an iterator $j$ from the iterable and calling \code{moveNext()} on it, execution of the body of $f$ will begin. When $f$ terminates, $j$ is positioned after its last element, so that its current value is \NULL{} and the current call to \code{moveNext()} on $j$ returns false, as will all further calls.
+
+Each iterator starts a separate computation. If the \SYNC* function is impure, the sequence of values yielded by each iterator may differ. 
+
+\commentary{
+One can derive more than one iterator from a given iterable.   Note that operations on the iterable itself can create distinct iterators. An example would be \code{length}.  It is conceivable that different iterators might yield sequences of different length. The same care needs to be taken when writing \SYNC* functions as when
+writing an \code{Iterator} class. In particular, it should handle multiple
+simultaneous iterators gracefully. If the iterator depends on external state
+that might change, it should check that the state is still valid after every
+yield (and maybe throw a \code{ConcurrentModificationError} if it isn't).
+}
+
+\LMHash{}
+Each iterator runs with its own shallow copies of all local variables; in particular, each iterator has the same initial arguments, even if their bindings are modified by the function. 
+\commentary{
+Two executions of an iterator interact only via state outside the function.
+}
+% The alternative would be to cache the results of an iterator in the iterable, and check the cache at each \YIELD{}.  This would have strange issues as well. The yielded value might differ from the expression in the yield. And it is a potential memory leak as the cache is kept alive by any iterator.
+
+
+\LMHash{}
 If $f$ is synchronous and is not a generator (\ref{functions}) then execution of the body of $f$ begins immediately.  When $f$ terminates the current return value is returned to the caller.