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

@jyasskin approved this pull request.

A few final comments:

> +  download it themselves by reading from the <a for=/>response</a>'s <a for=response>body</a>'s
+  <a for=body>stream</a>.

Since we moved the method up in the paragraph:
```suggestion
  download it themselves.
```

> -  <p>If the <a for=/>request</a>'s <a for=request>mode</a> is "<code>navigate</code>" and its
-  <a for=request>redirect mode</a> is "<code>manual</code>", then callers need to follow a very
-  specific flow with this algorithm to get the intended behavior. They should compute the
-  appropriate <a for=response>location URL</a>, and if it is non-null or failure, then they should
-  call <a for="fetch controller">process the next manual redirect</a>. This will result in
-  <a for=fetch><i>processResponse</i></a> being called again, with the next <a for=/>response</a>
-  in the redirect chain.
-
- <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 clients 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 downloaded in its entirety into a
+  <a>byte sequence</a>, and then processed by the <a for=request>client</a>.

```suggestion
  <a>byte sequence</a>, and then processed by the client.
```

> -
-   <dt>failure
-   <dd>Attempting to <a for=body>fully read</a> the contents of the <a for=/>response</a>'s
-   <a for=response>body</a> failed, e.g., due to an I/O error.
-
-   <dt>a <a>byte sequence</a>
-   <dd><a for=body>Fully reading</a> the contents of the <a for=/>response</a>'s
-   <a for=response>body</a> succeeded.
-  </dl>
-
-  <p class=warning>A standard that uses this argument cannot operate on <a for=/>response</a>'s
-  <a for=response>body</a> itself as providing this argument will cause it to be read and it can be
-  read only once.
+  <p>In some cases, for example when playing video or progressively loading images, clients might
+  want to stream the response, and process it one chunk at a time. The <a for=/>response</a> is
+  handed over to the <a for=request>client</a> once the headers are processed, and the client

```suggestion
  handed over to the Fetch caller once the headers are processed, and the caller
```

> +<p>Note that the <a for=/>fetch</a> operation runs <a>in parallel</a>, and it posts
+the aforementioned callbacks to a given <a for=/>event loop</a> which is usually the
+<a for=request>client</a>'s <a for="environment settings object">global object</a>. To process

Globals aren't event loops .... How about:

```suggestion
<p>Note that the <a for=/>fetch</a> operation runs <a>in parallel</a>, and it usually posts
the aforementioned callbacks to the <a for=request>client</a>'s
<a for="environment settings object">responsible event loop</a>. To process
```

> -
-  <p class=warning>A standard that uses this argument cannot operate on <a for=/>response</a>'s
-  <a for=response>body</a> itself as providing this argument will cause it to be read and it can be
-  read only once.
+  <p>In some cases, for example when playing video or progressively loading images, clients might
+  want to stream the response, and process it one chunk at a time. The <a for=/>response</a> is
+  handed over to the <a for=request>client</a> once the headers are processed, and the client
+  continues from there.
+
+  <p>To process a <a for=/>response</a> chunk-by-chunk, pass an algorithm to the
+  <a for=fetch><i>processResponse</i></a> argument of <a for/>fetch</a>. The given
+  algorithm is passed a <a for=/>response</a> when the response's headers have been
+  received and is responsible for reading the <a for=/>response</a>'s
+  <a for=response>body</a>'s <a for=body>stream</a> in order to download the rest
+  of the response. For convenience, you may also pass an algorithm to the
+  <a for=fetch><i>processResponseEndOfBody</i></a> argument, which would be called once you have finished

```suggestion
  <a for=fetch><i>processResponseEndOfBody</i></a> argument, which is called once you have finished
```

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

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