Docs: Overhaul no-floating-promise messages and docs

[JoshuaKGoldberg]

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

Right now, @typescript-eslint/no-floating-promises logs quite a mouthful for its messages:

Promises must be awaited, end with a call to .catch, end with a call to .then with a rejection handler or be explicitly marked as ignored with the `void` operator.

So much text! Longer messages are less likely to be read by users - especially "error" (or "warning") messages like this one.

In addition, it's also missing the point that storing the Promise in a variable is considered an acceptable workaround by the rule (assuming you have unused variable detection enabled). #8046 is an example of a discussion asking about that.

This is a nuanced area. See replies to: https://twitter.com/flybayer/status/1469098848958222337, https://twitter.com/threepointone/status/1471458830626299911, https://twitter.com/nandafyi/status/1736164705448956388, and other threads from searching on no-floating-promises). I think we should rework the rule a bit to coach/encourage developers into treating the nuance with care:

• Make the error message much shorter (so folks will actually read the whole thing), and perhaps encourage them to read the docs for more info
• Mention the unused variable allowance in the docs
• Link to a blog post explaining how to enable our Promise/Thenable-area rules (perhaps a separate issue?)

Affected URL(s)

https://typescript-eslint.io/rules/no-floating-promises

[JoshuaKGoldberg]

Since #7008 was added to the 8 milestone for tracking, adding this as well. I think we'll really need to have good docs to make sure folks don't misuse this.

[JoshuaKGoldberg]

Btw, referencing #7008 & nodejs/node#51292 & reduxjs/redux-toolkit#4102: we should definitely mention strategies for frameworks/libraries to mark Promises as safe (or not expose them).

[JoshuaKGoldberg]

Note: #8573 has a good suggestion:

I fixed a no-floating-promises error by changing:

- promise.catch(() => {}).then(() => {})
+ promise.catch(() => {}).finally(() => {})

I think this is a good change! Since my .catch() handler couldn't reject, it's probably not even a change.

The .catch().then() form is mentioned on MDN and triggers this rule (playground). So it would be helpful if the docs on this rule included an example of the suggested refactor.

[JoshuaKGoldberg]

Marking as blocked on PRs implementing #7008 and #8404, as I'd neglected to note this publicly till now. 🙂

[JoshuaKGoldberg]

Now that #9186 is merged, I believe this is almost unblocked. I'd like to tackle it alongside #8517.

#8404 would be great too. Marking as blocked on that.