Update documentation on Stream.map

sdk/lib/async/stream.dart

Index: sdk/lib/async/stream.dart
diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart
index dff5b18f984c28548898c94bc96448666331c02a..252814d14c29f8575edbe1b4f964e147c6274f15 100644
--- a/sdk/lib/async/stream.dart
+++ b/sdk/lib/async/stream.dart
@@ -313,9 +313,17 @@ abstract class Stream<T> {
    * Creates a new stream that converts each element of this stream
    * to a new value using the [convert] function.
    *
+   * For each data event, `o`, in this stream, the returned stream
+   * will provide a data event with the value `convert(o)`.

[floitsch, 2015/12/16 13:39:35]

provides

[Lasse Reichstein Nielsen, 2015/12/16 13:45:11]

Done.

+   * If [convert] throws, the returned string will report that as an error

[floitsch, 2015/12/16 13:39:35]

reports the exception as an error event.

[Lasse Reichstein Nielsen, 2015/12/16 13:45:11]

Done. And string->stream :)

+   * event.
+   *
+   * Error and done events are passed through unchanged to the returned stream.
+   *
    * The returned stream is a broadcast stream if this stream is.
+   * The [convert] function is called once per data event per listener.
    * If a broadcast stream is listened to more than once, each subscription
-   * will individually execute `map` for each event.
+   * will individually call [convert] on each data event.
    */
   Stream/*<S>*/ map/*<S>*/(/*=S*/ convert(T event)) {
     return new _MapStream<T, dynamic/*=S*/>(this, convert);