Document difference between Stream.transform and Stream.map.

Fixes #36351

Bug: http://dartbug.com/36351
Change-Id: I75f98b8fdc3a34578adab96e9993089ea69e84bd
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/98346
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Nate Bosch <nbosch@google.com>

sdk/lib/async/stream.dart

@@ -689,7 +689,7 @@ abstract class Stream<T> {
   }
 
   /**
-   * Applies  [streamTransformer] to this stream.
+   * Applies [streamTransformer] to this stream.
    *
    * Returns the transformed stream,
    * that is, the result of `streamTransformer.bind(this)`.

sdk/lib/convert/json.dart

@@ -181,6 +181,9 @@ class JsonCodec extends Codec<Object, String> {
 }
 
 /// This class converts JSON objects to strings.
+///
+/// When used as a [StreamTransformer], this converter does not promise
+/// that the input object is emitted as a single string event.
 class JsonEncoder extends Converter<Object, String> {
   /// The string used for indention.
   ///
@@ -470,7 +473,14 @@ class _JsonUtf8EncoderSink extends ChunkedConversionSink<Object> {
   }
 }
 
-/// This class parses JSON strings and builds the corresponding objects.
+/// This class parses JSON strings and builds the corresponding value.
+///
+/// A JSON input must be the JSON encoding of a single JSON value,
+/// which can be a list or map containing other values.
+///
+/// When used as a [StreamTransformer], the input stream may emit
+/// multiple strings. The concatenation of all of these strings must
+/// be a valid JSON encoding of a single JSON value.
 class JsonDecoder extends Converter<String, Object> {
   final Function(Object key, Object value) _reviver;
 

sdk_nnbd/lib/async/stream.dart

@@ -668,7 +668,7 @@ abstract class Stream<T> {
   }
 
   /**
-   * Applies  [streamTransformer] to this stream.
+   * Applies [streamTransformer] to this stream.
    *
    * Returns the transformed stream,
    * that is, the result of `streamTransformer.bind(this)`.

sdk_nnbd/lib/convert/json.dart

@@ -473,6 +473,13 @@ class _JsonUtf8EncoderSink extends ChunkedConversionSink<Object?> {
 }
 
 /// This class parses JSON strings and builds the corresponding objects.
+///
+/// A JSON input must be the JSON encoding of a single JSON value,
+/// which can be a list or map containing other values.
+///
+/// When used as a [StreamTransformer], the input stream may emit
+/// multiple strings. The concatenation of all of these strings must
+/// be a valid JSON encoding of a single JSON value.
 class JsonDecoder extends Converter<String, Object?> {
   final Object? Function(Object? key, Object? value)? _reviver;