From 93ff9530aa20f584ffec11088d51d0b22a77f335 Mon Sep 17 00:00:00 2001
From: "Lasse R.H. Nielsen" <lrn@google.com>
Date: Fri, 6 Mar 2020 13:19:34 +0000
Subject: [PATCH] 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      |  2 +-
 sdk/lib/convert/json.dart      | 12 +++++++++++-
 sdk_nnbd/lib/async/stream.dart |  2 +-
 sdk_nnbd/lib/convert/json.dart |  7 +++++++
 4 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/sdk/lib/async/stream.dart b/sdk/lib/async/stream.dart
index cdb8211cc66..ed95a05b7f2 100644
--- a/sdk/lib/async/stream.dart
+++ b/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)`.
diff --git a/sdk/lib/convert/json.dart b/sdk/lib/convert/json.dart
index a834a9e633e..1fa356d705c 100644
--- a/sdk/lib/convert/json.dart
+++ b/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;
 
diff --git a/sdk_nnbd/lib/async/stream.dart b/sdk_nnbd/lib/async/stream.dart
index c4ee2f28411..565b9f49a26 100644
--- a/sdk_nnbd/lib/async/stream.dart
+++ b/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)`.
diff --git a/sdk_nnbd/lib/convert/json.dart b/sdk_nnbd/lib/convert/json.dart
index a75dbb57f46..95286027255 100644
--- a/sdk_nnbd/lib/convert/json.dart
+++ b/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;