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

@annevk commented on this pull request.



> -
- <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 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 there was a <a>network error</a>, failure if there was an
+  error while downloading, or a <a>byte sequence</a> representing the successfully obtained
+  <a for=response>body</a>.

This seems incorrect. It's null when there is no body, failure when there's a network error, and otherwise the body as a byte sequence.

>  
-<p>Aside from a <a for=/>request</a> the <a for=/>fetch</a> operation takes several optional
-arguments. For those arguments that take an algorithm: the algorithm will be called from a task (or
-in a <a for=/>parallel queue</a> if <a for=fetch><i>useParallelQueue</i></a> is true).
+<p>Once the <a for=/>request</a> is set up, determine how you would like to process the
+<a for=/>response</a>, and in particular at what stage you would like to receive a callback:

What I mean is that it doesn't mention the fetch operation at all in this introductory paragraph.

> -  <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 Fetch caller once the headers are processed, and the caller
+  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 is called once you have finished
+  obtaining the response and its <a for=response>body</a>. Note that unlike

Fully reading seems fine.

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

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