Please update `StreamController` documentation

[sgrekhov]

See StreamController.addStream() documentation:

sdk/sdk/lib/async/stream_controller.dart

Lines 295 to 297 in 4c3e916

	/// Events must not be added directly to this controller using [add],
	/// [addError], [close] or [addStream], until the returned future
	/// is complete.

May be it makes sense to add that in case of MultiStreamController it's also addSync, addErrorSync and closeSync?

StreamController.close():

sdk/sdk/lib/async/stream_controller.dart

Lines 252 to 253 in 4c3e916

	/// No further events can be added to a closed stream.
	///

What about done event? Calling close() twice doesn't produce any issues so it looks like sending done event to the closed stream is allowed.

sdk/sdk/lib/async/stream_controller.dart

Lines 255 to 256 in 4c3e916

	/// It is completed when the stream listeners is done sending events,
	/// This happens either when the done event has been sent,

Looks like a typo. Stream listeners are done sending events? May be listening? And there should be a dot at the end of line 255, not a comma.

sdk/sdk/lib/async/stream_controller.dart

Lines 259 to 260 in 4c3e916

	/// A stream controller will not complete the returned future until all
	/// listeners present when the done event is sent have stopped listening.

It's hard to understand what is meant. Please, rewrite.

Edit:
Also the folowing.

sdk/sdk/lib/async/stream_controller.dart

Lines 267 to 268 in 4c3e916

	/// If no one listens to a non-broadcast stream,
	/// or the listener pauses and never resumes,

Seems that "non-broadcast" here should be removed. It's possible to create a broadcast multi-listener stream by Stream.multi but the above will be true for it.

cc @lrhn

[sgrekhov]

StreamController.done:

sdk/sdk/lib/async/stream_controller.dart

Lines 275 to 276 in 9046485

	/// This happens either when the done event has been sent, or if the
	/// subscriber on a single-subscription stream is canceled.

In case of MultiStreamController it's not a single-subscription stream.

sdk/sdk/lib/async/stream_controller.dart

Lines 286 to 287 in 9046485

	/// If there is no listener on a non-broadcast stream,
	/// or the listener pauses and never resumes,

Again, "non-broadcast" seems excessive.

[sgrekhov]

StreamController.isPaused:

sdk/sdk/lib/async/stream_controller.dart

Lines 222 to 224 in 9046485

	/// A broadcast stream controller is never considered paused. It always
	/// forwards its events to all uncanceled subscriptions, if any,
	/// and let the subscriptions handle their own pausing and buffering.

It's not true for Stream.multi(..., isBroadcast: true).

[sgrekhov]

StreamController.onCancel:

sdk/sdk/lib/async/stream_controller.dart

Lines 197 to 200 in 9046485

	/// The callback which is called when the stream is canceled.
	///
	/// May be set to `null`, in which case no callback will happen.
	abstract FutureOr<void> Function()? onCancel;

This callback is also called on "done" event. Please add it to the documentation.

[lrhn]

It's not true for Stream.multi(..., isBroadcast: true).

It is! The text is not descriptive, it's prescriptive. That's what a valid broadcast stream must do.
The creator of a Stream.multi with the isBroadcast set to true must behave like a broadcast stream, otherwise they're breaking the contract.
(Which they can obviously do if they document that, but they should probably just not set isBroadcast to true then.)

This callback is also called on "done" event. Please add it to the documentation.

I'd have thought that was a bug. But ... having checked, it's been like that for 12 years, so let's say it's how it should be. It does ensure that the life-cycle of the controller always goes from onListen to onCancel.
(The close method calls _sendDone which callas an internal _cancel() to clear the internal state, which also calls _onCancel().)