Re: [heycam/webidl] Import the Promises Guide. (#772)

domenic commented on this pull request.



>          1.  Let |reason| be the result of [=converted to an IDL value|converting=]
             |R| to an IDL value of type {{any}}.
         1.  If there are no steps that are required to be run if the promise was rejected, then
             return <emu-val>undefined</emu-val>.
-        1.  Otherwise, return the result of performing any steps that were required to be run if the promise was rejected,
-            with |reason| as the rejection reason.
-    1.  Return [=!=] [$PerformPromiseThen$](|promise|, |onFulfilled|, |onRejected|).
+        1.  Let |result| be the result of performing any steps that were required to be run if the
+            promise was rejected, given |reason|.
+        1.  Return |result|, [=converted to an ECMAScript value=].
+    1.  Let |onRejected| be [=!=] [$CreateBuiltinFunction$](|onRejectedSteps|, « »):
+    1.  Let |constructor| be |promise|.\[[Promise]].\[[Realm]].\[[Intrinsics]].[[{{%Promise%}}]].
+    1.  Let |newCapability| be ? [$NewPromiseCapability$](|constructor|).
+    1.  Return [=!=] [$PerformPromiseThen$](|promise|.\[[Promise]], |onFulfilled|, |onRejected|, |newCapability|).
+
+    Note: If the provided steps return a value of type |T|, this algorithm returns a
+    <code>{{Promise}}&lt;<var ignore>T</var>&gt;</code>.

Maybe we should use a different letter than T here, since it could be anything. And we should note that if they throw, it'll return a rejected promise? Should we also talk about what happens if they return promises?? Hmm, maybe just saying that it behaves like .then() would summarize better?

> +        1.  Return.
+    1.  Let |index| be 0.
+    1.  Let |result| be a [=list=] containing |total| null values.
+    1.  [=list/For each=] |promise| of |promises|:
+        1.  Let |promiseIndex| be |index|.
+        1.  Let |fulfillmentHandler| be the following steps given |arg|:
+            1.  Set |result|[|promiseIndex|] to |arg|.
+            1.  Set |fullfilledCount| to |fullfilledCount| + 1.
+            1.  If |fullfilledCount| equals |total|, then perform |successSteps| given |result|.
+        1.  Let |fulfillmentHandler| be [=!=] [$CreateBuiltinFunction$](|fulfillmentHandler|, « »):
+        1.  Perform [$PerformPromiseThen$](|promise|, |fulfillmentHandler|, |rejectionHandler|).
+        1.  Set |index| to |index| + 1.
+</div>
+
+This phrase is useful when you wish to aggregate the result of multiple promises, and react to them
+all together, in the same way that {{Promise/all()|Promise.all()}} functions for JavaScript code.

Probably the clause "in the same way..." should move to the "get a promise for waiting for all". I think this was just missed when I separated the two operations in the promises guide.

> +        1.  [=Promise/Resolve=] |promise| with |results|.
+    1.  Let |failureSteps| be the following steps, given |reason|:
+        1.  [=Promise/Reject=] |promise| with |reason|.
+    1.  [=Promise/Wait for all=] with |promises|, given |successSteps| and |failureSteps|.
+    1.  Return |promise|.
+</div>
+
+This phrase is useful when you wish to aggregate the results of multiple promises, and then produce
+another promise from them.
+
+
+<h6 id="es-promise-examples">Examples</h6>
+
+<div class="example" id="promise-example-delay">
+
+    <code>delay</code> is a function that returns a promise that will be fulfilled in a number of

```suggestion
    <code>delay</code> is an operation that returns a promise that will be fulfilled in a number of
```

Or method? Anyway, same for the others...

> +
+    1.  Let |promise| be [=Promise/a new promise=] of type
+        <code>{{Promise}}&lt;<a lt="sequence type">sequence</a>&lt;|T|>></code> in |realm|.
+    1.  Let |successSteps| be the following steps, given |results|:
+        1.  [=Promise/Resolve=] |promise| with |results|.
+    1.  Let |failureSteps| be the following steps, given |reason|:
+        1.  [=Promise/Reject=] |promise| with |reason|.
+    1.  [=Promise/Wait for all=] with |promises|, given |successSteps| and |failureSteps|.
+    1.  Return |promise|.
+</div>
+
+This phrase is useful when you wish to aggregate the results of multiple promises, and then produce
+another promise from them.
+
+
+<h6 id="es-promise-examples">Examples</h6>

My intention with the "add a heading" comment was for this to stay a h5, i.e. have two siblings under the promise section. Arguably this section has examples of the general promise type definitions too.

> +    If any of the fetches fail, it will return [=Promise/rejected promise|a promise rejected with=]
+    that failure.
+
+    <pre highlight="webidl">
+        interface I {
+          Promise&lt;sequence&lt;Response>> batchRequest(sequence&lt;USVString> urls);
+        };
+    </pre>
+
+<div algorithm="batchRequest">
+
+    The <code>batchRequest(|urls|)</code> method steps are:
+
+    1.  Let |responsePromises| be « ».
+    1.  [=list/For each=] |url| of |urls|:
+        1.  Let |p| be the result of calling {{WindowOrWorkerGlobalScope/fetch()}} with |url|.

Well, the intent is to make it clear what happens when author code overrides `fetch()`.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/heycam/webidl/pull/772#pullrequestreview-279149503