Improve return-await rule description, and better explain stack trace benefits #8763
Description
Before You File a Documentation Request Please Confirm You Have Done The Following...
- I have looked for existing open or closed documentation requests that match my proposal.
- I have read the FAQ and my problem is not listed.
Suggested Changes
What is says it does:
Enforce consistent returning of awaited values.
What it actually does:
Enforce consistent awaiting of returned values.
Wordier but more complete version:
Enforce whether a returned promise is always awaited, never awaited, or awaited when inside a try/catch.
The reason I thought I wanted it to actually return the awaited value is to enable better stack traces, but I acknowledge I don't quite get the exact circumstances under which it's necessary to return the awaited expression to attain that benefit. It would be nice if the documentation made the stack trace behavior for the different options of this rule crystal clear, as it's difficult to really make an intelligent decision about this rule's options without this knowledge.
I think the stack trace of async code is not well understood by many people and the rule options' motivations remain unclear. Here is what I wrote for MDN, for reference: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#improving_stack_trace