Overview

Doc: https://typescript-eslint.io/rules/return-await#never

The "never" option really just enforces wrong and confusing behavior in error-handling scenarios. In #9364 (comment) / #9364 (comment) we're trying to update the docs in return-await and I'm finding it hard to say when you would want to use the option. @JoshuaKGoldberg and I are thinking this may be a reasonable time to just deprecate it rather than trying too hard to find something nice to say.

Note that

• the base rule no-return-await has unconditionally acted like "in-try-catch", not "never", since 2016 (see Fix: handle try/catch correctly in no-return-await (fixes #7581) eslint/eslint#7582) and eslint never added a "never" option
• I can't find any issues in our repo related to "never"
• the original motivation was more of an "it's easy to code up" than a terribly intentional justification (see Feature request - rule for await in async try catch return #994)

It looks like very few people are using this option: https://sourcegraph.com/search?q=context:global+file:.*eslint%7Cjs%7Cjson%7Cyaml%7Cyml%7Cyaml.*+/%40typescript-eslint%5C/return-await.*never/+-file:.*node_modules.*+-file:dist%5C/.*+count:200000&patternType=standard&sm=0

I propose we document it as deprecated (in #9364), to be removed in a future major version.