Fix and update StreamTransformer constructor documentation.

Fixes #46924

BUG= https://dartbug.com/46924

Change-Id: I8a5d2aa3f60680ec419c4f0d614f6ec186106b08
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/210360
Auto-Submit: Lasse R.H. Nielsen <[email protected]>
Reviewed-by: Nate Bosch <[email protected]>
Commit-Queue: Nate Bosch <[email protected]>

Author: lrhn

sdk/lib/async/stream.dart

@@ -1913,28 +1913,24 @@ abstract class StreamTransformer<S, T> {
   /// ```dart
   /// /// Starts listening to [input] and duplicates all non-error events.
   /// StreamSubscription<int> _onListen(Stream<int> input, bool cancelOnError) {
-  ///   late StreamSubscription<String> subscription;
-  ///   // Create controller that forwards pause, resume and cancel events.
-  ///   var controller = new StreamController<String>(
-  ///       onPause: () {
-  ///         subscription.pause();
-  ///       },
-  ///       onResume: () {
-  ///         subscription.resume();
-  ///       },
-  ///       onCancel: () => subscription.cancel(),
-  ///       sync: true); // "sync" is correct here, since events are forwarded.
-  ///
-  ///   // Listen to the provided stream.
-  ///   subscription = input.listen((data) {
-  ///     // Duplicate the data.
-  ///     controller.add(data);
-  ///     controller.add(data);
-  ///   },
-  ///       onError: controller.addError,
-  ///       onDone: controller.close,
-  ///       cancelOnError: cancelOnError);
-  ///
+  ///   // Create the result controller.
+  ///   // Using `sync` is correct here, since only async events are forwarded.
+  ///   var controller = StreamController<int>(sync: true);
+  ///   controller.onListen = () {
+  ///     var subscription = input.listen((data) {
+  ///       // Duplicate the data.
+  ///       controller.add(data);
+  ///       controller.add(data);
+  ///     },
+  ///         onError: controller.addError,
+  ///         onDone: controller.close,
+  ///         cancelOnError: cancelOnError);
+  ///     // Controller forwards pause, resume and cancel events.
+  ///     controller
+  ///       ..onPause = subscription.pause
+  ///       ..onResume = subscription.resume
+  ///       ..onCancel = subscription.cancel;
+  ///   };
   ///   // Return a new [StreamSubscription] by listening to the controller's
   ///   // stream.
   ///   return controller.stream.listen(null);