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

domenic 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

Yeah, we should be using Infra.

In any case, it's clear this isn't as straightforward for at least you as a reader as it is for me as the writer, so I guess we can explicitly make these sections non-normative, even though per my reading they do not contain any normative text anyway.

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