whatwg
explain better what the pull method should do in the underlying source API
The specification of the pull method in 4.2.3 doesn't actually say how it's supposed to return new chunks. From example 10.4 it seems that the way to return new chunks is to call controller.enqueue(), which is the same as a push source. But it should probably say so explicitly?
Or, possibly this could be explained in the mdn documentation if it doesn't belong in the spec. As it is, how to implement a push method is somewhat mysterious.
Similarly, to indicate that a stream is finished, it can call controller.close(), but this isn't actually said.
Do any of the examples in https://streams.spec.whatwg.org/#creating-examples help? Those are linked directly from the section you talk about. I don't think duplicating them is especially useful.
Yes, the examples are good and I don't think they should be inlined. The verbage could be improved a bit? I'll send a patch.
Looking at it again, I think it's a bigger issue with the mdn documentation, which has no pull examples.
On second thought, I'm not sure how to contribute a patch, but here's what I have in mind.
A call to the pull method signals that more chunks should be sent using the supplied controller's enqueue() method. Typically this happens asynchronously, and may happen indirectly in the case of push sources.
A slight ambiguity here: I believe that start() and pull() always receive the same controller and it doesn't matter which one you call enqueue() on. Is this actually specified, though?
Yep, that's specified! E.g. https://streams.spec.whatwg.org/#set-up-readable-stream-default-controller-from-underlying-source passes (well, closes over) the same controller variable for both start and pull.