Incorrect description for constructor StreamController.broadcast()

[alsemenov]

The description for constructor StreamController.broadcast() reads:

A controller where stream can be listened to more than once.

The Stream returned by stream is a broadcast stream. It can be listened to more than once.

A Stream should be inert until a subscriber starts listening on it (using the onListen callback to start producing events). Streams should not leak resources (like websockets) when no user ever listens on the stream.

Broadcast streams do not buffer events when there is no listener.

I think highlighted sentences should be removed as not relevant to the subject. They look like requirements for implementation, while should be a description of implementation.

[alsemenov]

The same sentence is also present in description of StreamController constructor.

StreamController({ void onListen(), void onPause(), void onResume(), dynamic onCancel(), bool sync: false }) A controller with a stream that supports only one single subscriber.

If sync is true, the returned stream controller is a SynchronousStreamController, and must be used with the care and attention necessary to not break the Stream contract. See Completer.sync for some explanations on when a synchronous dispatching can be used. If in doubt, keep the controller non-sync.

A Stream should be inert until a subscriber starts listening on it (using the onListen callback to start producing events). Streams should not leak resources (like websockets) when no user ever listens on the stream.

The controller buffers all incoming events until a subscriber is registered, but this feature should only be used in rare circumstances.

[lrhn]

It is describing the behavior that a user of the stream expects - that not listening to the stream should be safe, no significant resources should be leaked by keeping the stream alive and not listening to it.

It is intended as a guide on how to use the stream controller (don't start doing anything before you get an onListen), so I think the paragraph, or something like it, belongs on the stream controller. We might want to tweak the wording to make the intent more clear.

[alsemenov]

Please, correct the wording. A Stream should ... sounds very strange in the description of the concrete implementation.