Docs: improve documentation of no-return-await

[LinusU]

First of all, I know that there have been a lot of discussions on wether this rule is a good one or not. I do not want to bring up that discussion here at all. I just want to clarify the documentation to better explain the implications, I don't want to advocate for either turning this rule on or off.

---

I've had some team member asking why we are using return await, especially after reading the current version of the documentation for no-return-await. The reason we are using return await is because otherwise the functions are missing from the stack traces if an error is thrown asynchronously in the promise that is being returned.

My intention with this change is to document that pitfall, and to clarify exactly what is being skipped when not using return await (that is, that the function is either still on the call stack, or not)

I'm very open to suggestion on more improvements that we can do here! ❤️

[jsf-clabot]

All committers have signed the CLA.

[netlify]

Deploy preview for eslint ready!

Built with commit 46d7ac8

https://deploy-preview-716--eslint.netlify.app

[LinusU]

I used the following example to demonstrate for my co-worker, although I don't think that we should add it here since it might be a bit much to try to explain that in depth?

const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms))

async function inner () {
  await sleep(1000)
  console.log(new Error('Example error that could be thrown here').stack)
  return 'Hello, World!'
}

async function outer_with_await () {
  return await inner()
}

async function outer_without_await () {
  return inner()
}

async function main () {
  console.log('====== With Await =======')
  await outer_with_await()
  console.log('=========================')

  console.log('===== Without Await =====')
  await outer_without_await()
  console.log('=========================')
}

main()

Which prints:

====== With Await =======
Error: Example error that could be thrown here
    at inner (/Users/linus/example.js:5:15)
    at async outer_with_await (/Users/linus/example.js:10:10)
    at async main (/Users/linus/example.js:19:3)
=========================
===== Without Await =====
Error: Example error that could be thrown here
    at inner (/Users/linus/example.js:5:15)
    at async main (/Users/linus/example.js:22:3)
=========================

[nzakas]

Thanks! Can you please submit these changes in the main ESLint repo? This repo is just the live site and the all of the docs are just copied over from the main repo each release.

[LinusU]

Thank you for pointing me in the right direction, sent it here: eslint/eslint#13215

I should probably note that I clicked "Edit this page" on the bottom of the page in question, maybe that should be relinked? 🤔

Do you want me to close this one? ☺️

[kaicataldo]

Ah, thanks for pointing that. We should definitely fix that.

[kaicataldo]

PR to fix those links here. Thanks for reporting this!

[LinusU]

This was merged here: eslint/eslint#13215