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

I wouldn't interpret the absence of the words "must" or "should" to mean that a statement in a normative section was not a requirement.

Our algorithms don't say "must" or "should" either. In fact, we seem to be missing a bit of boilerplate somewhere that would make them a "must". The [[INFRA]](https://infra.spec.whatwg.org/#algorithms) standard has something like that, but we're not using it.

-- 
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_r168532659