Update stream iterator doc and add test.

Update stream iterator doc and add test.

BUG= http://dartbug.com/15449
R=sgjesse@google.com

Committed: https://code.google.com/p/dart/source/detail?r=31317

[Søren Gjesse, 2013-12-19 15:28:35]

lgtm

https://codereview.chromium.org/99463005/diff/1/tests/lib/async/stream_iterat...
File tests/lib/async/stream_iterator_test.dart (right):

https://codereview.chromium.org/99463005/diff/1/tests/lib/async/stream_iterat...
tests/lib/async/stream_iterator_test.dart:71: test("stream iterator read badly",
() {
Why is this test called "read badly"?

[Lasse Reichstein Nielsen, 2013-12-19 15:30:17]

https://codereview.chromium.org/99463005/diff/1/tests/lib/async/stream_iterat...
File tests/lib/async/stream_iterator_test.dart (right):

https://codereview.chromium.org/99463005/diff/1/tests/lib/async/stream_iterat...
tests/lib/async/stream_iterator_test.dart:71: test("stream iterator read badly",
() {
Short for "read current at a time when you shouldn't", but it's more like a
"moveNext badly". I'll change it to something less cute.

[Lasse Reichstein Nielsen, 2013-12-20 07:14:57]

Committed patchset #2 manually as r31317 (presubmit successful).