docs: clarify promise-function-async docs
#9289
Conversation
|
Thanks for the PR, @benmccann! 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. |
✅ Deploy Preview for typescript-eslint ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
| @@ -9,16 +9,9 @@ import TabItem from '@theme/TabItem'; | |||
| > | |||
| > See **https://typescript-eslint.io/rules/promise-function-async** for documentation. | |||
|
|
|||
| Ensures that each function is only capable of: | |||
| Ensures that functions returning promises can only return rejected promises when an error is encountered and cannot throw. This simplifies the API for callers by making it so that they only need to handle errors in a single manner. | |||
There was a problem hiding this comment.
🤔 I don't think this is better at explaining the rule. At its core, promise-function-async enforces that "any function or method that returns a Promise to be marked async". This explanation is a rewording of the technical backing but both are pretty in-the-weeds.
I think I'd rather take this on myself as part of #8088 actually. Unless @kirkwaiblinger do you have specific wording you wanted to work with?
There was a problem hiding this comment.
I agree that this is in need of more significant overhaul from a team member 👍
|
Hey @benmccann! 👋 We appreciate the suggestions and grammar fixup! I'm going to close this PR in light of #9289 (comment), but, to be clear, that doesn't indicate that there's anything inadequate with your suggestions! It's just that in this case, they'll be superseded by some existing, ongoing efforts around improving our promise rule docs to be more cohesive as a whole. Thanks for the PR and discussions! 🙂 |
PR Checklist
asyncunless theyawait#9284 (comment)Overview
Reword the description much more simply
Fix an ungrammatical phrase in the callout that was hard to parse - "make the return type explicitly to allow the rule to pass"