Reordering based on feedback

Author: jakearchibald

src/content/en/fundamentals/getting-started/primers/async-functions.md

@@ -30,7 +30,7 @@ If you use the `async` keyword before a function definition, you can then use
 until the promise settles. If the promise fulfills, you get the value back. If
 the promise rejects, the rejected value is thrown.
 
-Note: If you're unfamiliar with promises & promise terminology, check out [our
+Note: If you're unfamiliar with promises, check out [our
 promises guide](/web/fundamentals/getting-started/primers/promises).
 
 ## Example: Logging a fetch
@@ -63,7 +63,7 @@ And here's the same thing using async functions:
 It's the same number of lines, but all the callbacks are gone. This makes it way
 easier to read, especially for those less familiar with promises.
 
-## Return values
+## Async return values
 
 Calling an async function returns a promise for whatever the function returns or
 throws. So with:
@@ -87,56 +87,10 @@ throws. So with:
 
 …calling `foo()` returns a promise that *rejects* with `Error('bar')`.
 
-## Other async function syntax
-
-We've seen `async function() {}` already, but the `async` keyword can be used
-with other function syntax:
-
-### Arrow functions
-
-    // map some URLs to json-promises
-    const jsonPromises = urls.map(async url => {
-      const response = await fetch(url);
-      return response.json();
-    });
-
-Note: `array.map(func)` doesn't care that I gave it an async function, it just
-sees it as a function that returns a promise. It won't wait for the first
-function to complete before calling the second.
-
-### Object methods
-
-    const storage = {
-      async getAvatar(name) {
-        const cache = await caches.open('avatars');
-        return cache.match(`/avatars/${name}.jpg`);
-      }
-    };
-
-    storage.getAvatar('jaffathecake').then(…);
-
-### Class methods
-
-    class Storage {
-      constructor() {
-        this.cachePromise = caches.open('avatars');
-      }
-
-      async getAvatar(name) {
-        const cache = await this.cachePromise;
-        return cache.match(`/avatars/${name}.jpg`);
-      }
-    }
-
-    const storage = new Storage();
-    storage.getAvatar('jaffathecake').then(…);
-
-Note: Class constructors and getters/settings cannot be async.
-
 ## Example: Streaming a response
 
 The benefit of async functions increases in more complex examples. Say we wanted
-to stream a response while logging out the chunks and returning the final size.
+to stream a response while logging out the chunks, and return the final size.
 
 Note: The phrase "logging out the chunks" made me sick in my mouth.
 
@@ -170,13 +124,15 @@ Let's try that again with async functions:
     async function getResponseSize(url) {
       const response = await fetch(url);
       const reader = response.body.getReader();
-      let result;
+      let result = await reader.read();
       let total = 0;
 
-      while ((result = await reader.read()) && !result.done) {
+      while (!result.done) {
         const value = result.value;
         total += value.length;
         console.log('Received chunk', value);
+        // get the next result
+        result = await reader.read();
       }
 
       return total;
@@ -194,6 +150,52 @@ Note: I'm sort-of in love with streams. If you're unfamiliar with streaming,
 guide](https://jakearchibald.com/2016/streams-ftw/#streams-the-fetch-api){:
 .external}.
 
+## Other async function syntax
+
+We've seen `async function() {}` already, but the `async` keyword can be used
+with other function syntax:
+
+### Arrow functions
+
+    // map some URLs to json-promises
+    const jsonPromises = urls.map(async url => {
+      const response = await fetch(url);
+      return response.json();
+    });
+
+Note: `array.map(func)` doesn't care that I gave it an async function, it just
+sees it as a function that returns a promise. It won't wait for the first
+function to complete before calling the second.
+
+### Object methods
+
+    const storage = {
+      async getAvatar(name) {
+        const cache = await caches.open('avatars');
+        return cache.match(`/avatars/${name}.jpg`);
+      }
+    };
+
+    storage.getAvatar('jaffathecake').then(…);
+
+### Class methods
+
+    class Storage {
+      constructor() {
+        this.cachePromise = caches.open('avatars');
+      }
+
+      async getAvatar(name) {
+        const cache = await this.cachePromise;
+        return cache.match(`/avatars/${name}.jpg`);
+      }
+    }
+
+    const storage = new Storage();
+    storage.getAvatar('jaffathecake').then(…);
+
+Note: Class constructors and getters/settings cannot be async.
+
 ## Careful! Avoid going too sequential
 
 Although you're writing code that looks synchronous, ensure you don't miss the