Clarifications in the async / await section (mbeaudru#69)

Minor bugfixes and clarifications

Author: Svenskunganka

README.md

@@ -1267,45 +1267,45 @@ For classes understanding:
 
 In addition to [Promises](#promises), there is a new syntax you might encounter to handle asynchronous code named *async / await*.
 
-The purpose of async/await functions is to simplify the behavior of using promises synchronously and to perform some behavior on a group of Promises. Just as Promises are similar to structured callbacks, async/await is similar to combining generators and promises. ([Ref: MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function))
+The purpose of async/await functions is to simplify the behavior of using promises synchronously and to perform some behavior on a group of Promises. Just as Promises are similar to structured callbacks, async/await is similar to combining generators and promises. Async functions *always* returns a Promise. ([Ref: MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function))
 
-> **Note :** You must understand what are promises and how they work before trying to understand async / await since they rely on it.
+> **Note :** You must understand what promises are and how they work before trying to understand async / await since they rely on it.
 
 > **Note 2:** [*await* must be used in an *async* function](https://hackernoon.com/6-reasons-why-javascripts-async-await-blows-promises-away-tutorial-c7ec10518dd9#f3f0), which means that you can't use await in the top level of our code since that is not inside an async function.
 
 #### Sample code
 
 ```js
 async function getGithubUser(username) { // async keyword allows usage of await in the function and means function returns a promise
-  const response = await fetch(`https://api.github.com/users/${username}`); // "synchronously" waiting fetch promise to resolve before going to next line
+  const response = await fetch(`https://api.github.com/users/${username}`); // Execution is paused here until the Promise returned by fetch is resolved
   return response.json();
 }
 
 getGithubUser('mbeaudru')
   .then(user => console.log(user)) // logging user response - cannot use await syntax since this code isn't in async function
-  .catch(err => console.log(err)); // if an error is raised in our async function, we will catch it here
+  .catch(err => console.log(err)); // if an error is thrown in our async function, we will catch it here
 ```
 
 #### Explanation with sample code
 
 *Async / Await* is built on promises but they allow a more imperative style of code.
 
-*async* operator turns a function into a *promise* in which you can use the *await* operator.
+The *async* operator marks a function as asynchronous and will always return a *Promise*. You can use the *await* operator in an *async* function to pause execution on that line until the returned Promise from the expression either resolves or rejects.
 
 ```js
 async function myFunc() {
   // we can use await operator because this function is async
   return "hello world";
 }
 
-myFunc().then(msg => console.log(msg)) // "hello world" -- myFunc is turned into a promise because of async operator
+myFunc().then(msg => console.log(msg)) // "hello world" -- myFunc's return value is turned into a promise because of async operator
 ```
 
-When the *return* statement of an async function is reached, the promise is fulfilled with the value returned. If an error is thrown inside an async function, the promise state will turn to *rejected*.
+When the *return* statement of an async function is reached, the Promise is fulfilled with the value returned. If an error is thrown inside an async function, the Promise state will turn to *rejected*. If no value is returned from an async function, a Promise is still returned and resolves with no value when execution of the async function is complete.
 
-*await* operator is used to wait for a *Promise* to be fulfilled and only can be used inside an *async* function body. When encountered, the code execution is paused until the promise is fulfilled.
+*await* operator is used to wait for a *Promise* to be fulfilled and can only be used inside an *async* function body. When encountered, the code execution is paused until the promise is fulfilled.
 
-> **Note :** *fetch* is a Promise that allows to do an AJAX request
+> **Note :** *fetch* is a function that returns a Promise that allows to do an AJAX request
 
 Let's see how we could fetch a github user with promises first:
 
@@ -1323,7 +1323,7 @@ Here's the *async / await* equivalent:
 
 ```js
 async function getGithubUser(username) { // promise + await keyword usage allowed
-  const response = await fetch(`https://api.github.com/users/${username}`); // Execution stops here until fetch promise is fulfilled.
+  const response = await fetch(`https://api.github.com/users/${username}`); // Execution stops here until fetch promise is fulfilled
   return response.json();
 }
 
@@ -1336,11 +1336,13 @@ getGithubUser('mbeaudru')
 
 For instance, if you need to get a token in order to be able to fetch a blog post on a database and then the author informations:
 
+> **Note :** *await* expressions needs to be wrapped in parentheses to call its resolved value's methods and properties on the same line.
+
 ```js
 async function fetchPostById(postId) {
-  const token = await fetch('token_url');
-  const post = await fetch(`/posts/${postId}?token=${token}`);
-  const author = await fetch(`/users/${post.authorId}`);
+  const token = (await fetch('token_url')).json().token;
+  const post = (await fetch(`/posts/${postId}?token=${token}`)).json();
+  const author = (await fetch(`/users/${post.authorId}`)).json();
 
   post.author = author;
   return post;
@@ -1353,41 +1355,41 @@ fetchPostById('gzIrzeo64')
 
 ##### Error handling
 
-Unless we add *try / catch* blocks around *await* expressions, uncaught exceptions – regardless of whether they were raised in the body of your *async* function or while it’s suspended during *await* – will reject the promise returned by the *async* function. [(Ref: PonyFoo)](https://ponyfoo.com/articles/understanding-javascript-async-await#error-handling).
+Unless we add *try / catch* blocks around *await* expressions, uncaught exceptions – regardless of whether they were thrown in the body of your *async* function or while it’s suspended during *await* – will reject the promise returned by the *async* function. Using the `throw` statement in an async function is the same as returning a Promise that rejects. [(Ref: PonyFoo)](https://ponyfoo.com/articles/understanding-javascript-async-await#error-handling).
 
 > **Note :** Promises behave the same!
 
 With promises, here is how you would handle the error chain:
 
 ```js
 function getUser() { // This promise will be rejected!
-  return new Promise((res, rej) => rej("User not found !"))
-};
+  return new Promise((res, rej) => rej("User not found !"));
+}
 
 function getAvatarByUsername(userId) {
-  return getUser(userId).then(user => res(user.avatar))
+  return getUser(userId).then(user => user.avatar);
 }
 
 function getUserAvatar(username) {
-  return getAvatarByUsername(username).then(avatar => res({ username, avatar }))
+  return getAvatarByUsername(username).then(avatar => ({ username, avatar }));
 }
 
 getUserAvatar('mbeaudru')
   .then(res => console.log(res))
   .catch(err => console.log(err)); // "User not found !"
 ```
 
-With *async / await*:
+The equivalent with *async / await*:
 
 ```js
-function getUser() { // This promise will be rejected!
-  return new Promise((res, rej) => rej("User not found !"))
-};
+async function getUser() { // The returned promise will be rejected!
+  throw "User not found !";
+}
 
 async function getAvatarByUsername(userId) => {
   const user = await getUser(userId);
   return user.avatar;
-};
+}
 
 async function getUserAvatar(username) {
   var avatar = await getAvatarByUsername(username);