Update documentation of StreamIterator, improve tests.

Update documentation of StreamIterator, improve tests.

R=sgjesse@google.com

Committed: https://github.com/dart-lang/sdk/commit/f529055c1b01eba73a1a17e723513f9a6019a13a

[Lasse Reichstein Nielsen, 2015-07-03 10:58:06]

lrn@google.com changed reviewers:
+ sgjesse@google.com

[Søren Gjesse, 2015-07-03 11:06:52]

lgtm, with a few questions

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:1681: * The function must not be called again until
the future returned by a
"must not": What happens if that is violated? StateError?

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:1687: * (whether with another value or with an error),
When can "another value" be anything but false?

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:1720: * as will all further calls to [moveNext].
So moveNext cannot distinguish between end of stream and cancel. Should there be
a canceled exception in this case?

[Lasse Reichstein Nielsen, 2015-07-03 11:21:17]

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart
File sdk/lib/async/stream.dart (right):

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:1681: * The function must not be called again until
the future returned by a
Yes, it throws StateError. We don't document that.

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:1687: * (whether with another value or with an error),
It *should* not, but this is an interface, but we can't guarantee that an
implementation won't do something else.

But let's state that it must complete with true or false, then it's the
implementation's fault if it doesn't.

https://codereview.chromium.org/1216123004/diff/1/sdk/lib/async/stream.dart#n...
sdk/lib/async/stream.dart:1720: * as will all further calls to [moveNext].
I don't think it's worth it.
The code calling cancel should also be the code calling moveNext, so it should
be able to coordinate that. It should not need to introduce an error that you
have to handle as well. That means that any error would come from the stream.

[Lasse Reichstein Nielsen, 2015-07-03 11:23:44]

Committed patchset #2 (id:20001) manually as
f529055c1b01eba73a1a17e723513f9a6019a13a (presubmit successful).

[ahe, 2015-07-07 07:30:14]

Thank you!