fix(eslint-plugin): [return-await] don't error for in-try-catch if the return is in a catch without a finally

[soobing]

Fixes #2344

Added below two TC, and fixed.

• if you return a promise within a catch, and there is no finally, then it must not be awaited.
• if you return a promise within a finally, then it must not be awaited.

[typescript-eslint]

Thanks for the PR, @soobing!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

---

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint. As a thank you, your profile/company logo will be added to our main README which receives thousands of unique visitors per day.

[codecov]

Codecov Report

Merging #2356 into master will increase coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #2356      +/-   ##
==========================================
+ Coverage   92.81%   92.82%   +0.01%     
==========================================
  Files         290      290              
  Lines        9453     9481      +28     
  Branches     2647     2657      +10     
==========================================
+ Hits         8774     8801      +27     
- Misses        322      323       +1     
  Partials      357      357              

Flag	Coverage Δ
#unittest	92.82% <ø> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
packages/eslint-plugin/src/rules/return-await.ts	95.69% <ø> (-0.08%)	⬇️
packages/experimental-utils/src/ts-eslint/Scope.ts	100.00% <0.00%> (ø)
...es/eslint-plugin/src/rules/no-use-before-define.ts	94.36% <0.00%> (ø)
packages/eslint-plugin/src/rules/no-unused-vars.ts	93.06% <0.00%> (+0.21%)	⬆️

[bradzacher]

So the issue in question isn't that the code was erroring - it's that it shouldn't error.

The code should work in the following way for in-try-catch mode:

• if you return a promise within a try, then it must be awaited.
• if you return a promise within a catch, and there is no finally, then it must not be awaited.
• if you return a promise within a catch, and there is a finally, then it must be awaited.
• if you return a promise within a finally, then it must not be awaited.

[soobing]

Aha.. thanks for the kind explanation.
I will try again.

[soobing]

@bradzacher
Hi, I tried again. Please review my code 😋.
I also change this PR's description #2356 (comment)

[soobing]

@bradzacher hi, could you review again? I don't know How to ask review again so I am mentioning 🦊

[bradzacher]

The code LGTM.
Thanks for your work!

Could you please update the docs for the in-try-catch option?

Specifically, could you make it very clear how it works, doing something like this will be good.

---

in-try-catch

Requires that a returned promise must be awaited in try-catch-finally blocks, and disallows it elsewhere. Specifically:

• if you return a promise within a try, then it must be awaited.
• if you return a promise within a catch, and there is no finally, then it must not be awaited.
• if you return a promise within a catch, and there is a finally, then it must be awaited.
• if you return a promise within a finally, then it must not be awaited.

[soobing]

@bradzacher Thanks for review!
I updated the docs and also added some examples.

[bradzacher]

LGTM - thanks for your work