Re: [whatwg/streams] A variety of clarity and documentation improvements (#875)

ricea commented on this pull request.



> @@ -502,6 +470,91 @@ ReadableStream(<var>underlyingSource</var> = {}, { <var>size</var>, <var>highWat
   1. Otherwise, throw a *RangeError* exception.
 </emu-alg>
 
+<h4 id="underlying-source-api">Underlying Source API</h4>
+
+The {{ReadableStream()}} constructor accepts as its first argument a JavaScript object representing the <a>underlying
+source</a>. Such objects may contain any of the following properties:
+
+<dl>
+  <dt><dfn method for="underlying source">start(<var>controller</var>)</dfn></dt>
+  <dd>
+    <p>A function that is called immediately upon creation of the {{ReadableStream}}.</p>
+
+    <p>Typically this is used adapt a <a>push source</a> by setting up relevant event listeners, as in the example of
+    [[#example-rs-push-no-backpressure]], or to acquire access to a <a>pull source</a>, as in [[#example-rs-pull]].</p>
+
+    <p>If this setup process is asynchronous, it can return a promise to signal success or failure; a rejected promise

That's my preference. Different people can disagree over whether a particular statement constitutes a requirement or not.

I like that the standard unambiguously defines consistent behaviour, even when it's wrong.

But I'm just concerned, not dead against it. If there's a benefit to making these sections normative then we can do that.

I can add the reference to infra if you are busy. I assume we just need one sentence in the "Conventions" section at the end?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/pull/875#discussion_r168778341