Add information to `no-return-await` docs about potential pitfalls.

return await has subtly different semantics from just return in async functions. Example:

async function failing() {
  throw new Error('foo');
}

async function noAwait() {
  try {
    return failing();
  } catch (e) {
    return 'oops';
  }
}


async function withAwait() {
  try {
    return await failing();
  } catch (e) {
    return 'oops';
  }
}

noAwait().then(console.log, console.warn);
withAwait().then(console.log, console.warn);

This will call console.warn with the ‘foo’ error, which is thrown from noAwait. But it will log oops from the withAwait function. This is confusing behaviour, which might completely catch people off guard. So no, the await after return is not always superfluous, and recommending it’s removal might lead to subtle changes that was not expected.

[not-an-aardvark]

Sounds good to me!

[platinumazure]

@not-an-aardvark Any direction you want to provide in response to this comment? Or does the proposal there sound good? Thanks!