Re: [whatwg/fetch] Editorial: Reword how-to section to explain how to use callbacks & controller (PR #1614)

@domenic approved this pull request.

LGTM with a few nits

> -
- <dt><a for=fetch><i>processResponseEndOfBody</i></a>
- <dd><p>Takes an algorithm that will be passed a <a for=/>response</a>. Indicates the network is
- done transmitting the response. This does not read <a for=/>response</a>'s
- <a for=response>body</a>.
+  <p>This is the most common way in which invokers handle a <a for=/>response</a>, for example
+  <a lt="fetch a classic script">scripts</a> and <a lt="fetch a style resource">style resources</a>.
+  The <a for=/>response</a>'s <a for=response>body</a> is obtained in its entirety into a
+  <a>byte sequence</a>, and then processed by the client.
+
+  <p>To process a <a for=/>response</a> upon completion, pass an algorithm as the
+  <a for=fetch><i>processResponseConsumeBody</i></a> argument of <a for=/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> and null, failure, or a <a>byte sequence</a>.
+  The second argument would be null if, for example, the <a for=/>response</a> is a
+  <a>network error</a>, has a <a>null body status</a> (e.g. 204), or if the <a for=/>request</a>'s
+  <a for=request>method</a> is `<code>HEAD</code>. It would be failure if there was an I/O error

```suggestion
  <a for=request>method</a> is `<code>HEAD</code>`. It would be failure if there was an I/O error
```

> +  while reading the <a for=response>body</a>, or a <a>byte sequence</a> representing the
+  successfully obtained <a for=response>body</a>.

```suggestion
  while reading the <a for=response>body</a>. It would be a <a>byte sequence</a> representing the
  <a for=response>body</a> if the body is successfully read.
```

> +  The <a for=/>response</a>'s <a for=response>body</a> is obtained in its entirety into a
+  <a>byte sequence</a>, and then processed by the client.
+
+  <p>To process a <a for=/>response</a> upon completion, pass an algorithm as the
+  <a for=fetch><i>processResponseConsumeBody</i></a> argument of <a for=/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> and null, failure, or a <a>byte sequence</a>.
+  The second argument would be null if, for example, the <a for=/>response</a> is a
+  <a>network error</a>, has a <a>null body status</a> (e.g. 204), or if the <a for=/>request</a>'s
+  <a for=request>method</a> is `<code>HEAD</code>. It would be failure if there was an I/O error
+  while reading the <a for=response>body</a>, or a <a>byte sequence</a> representing the
+  successfully obtained <a for=response>body</a>.
+
+  <div id=example-callback-upon-completion class=example>
+   <ol>
+    <li><p>Let <var>request</var> be a <a for=/>request</a> whose <a for=request>URL</a> is
+    <code>https://stuff.example.com</code>, and whose <a for=request>client</a> is <a>this</a>'s

All three example URLs should probably end in `/` so that they look like valid URL serializations.

> - <dd><p>Takes an algorithm that will be passed a <a for=/>response</a>. Indicates the network is
- done transmitting the response. This does not read <a for=/>response</a>'s
- <a for=response>body</a>.
+  <p>This is the most common way in which invokers handle a <a for=/>response</a>, for example
+  <a lt="fetch a classic script">scripts</a> and <a lt="fetch a style resource">style resources</a>.
+  The <a for=/>response</a>'s <a for=response>body</a> is obtained in its entirety into a
+  <a>byte sequence</a>, and then processed by the client.
+
+  <p>To process a <a for=/>response</a> upon completion, pass an algorithm as the
+  <a for=fetch><i>processResponseConsumeBody</i></a> argument of <a for=/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> and null, failure, or a <a>byte sequence</a>.
+  The second argument would be null if, for example, the <a for=/>response</a> is a
+  <a>network error</a>, has a <a>null body status</a> (e.g. 204), or if the <a for=/>request</a>'s
+  <a for=request>method</a> is `<code>HEAD</code>. It would be failure if there was an I/O error
+  while reading the <a for=response>body</a>, or a <a>byte sequence</a> representing the
+  successfully obtained <a for=response>body</a>.

Hmm yeah, in the current spec it's a dl: https://fetch.spec.whatwg.org/#fetch-elsewhere-fetch . Maybe just keep that dl?

-- 
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/fetch/pull/1614#pullrequestreview-1419935727
You are receiving this because you are subscribed to this thread.

Message ID: <whatwg/fetch/pull/1614/review/1419935727@github.com>