require-throws: false positive in async function

[regseb]

Expected behavior

Do not report require-throws when a throw is added in an async function (because the function returns a rejected promise).

Actual behavior

If an async function contains a throw, ESLint report require-throws rule:

/home/regseb/testcase/index.js
  1:1  error  Missing JSDoc @throws declaration  jsdoc/require-throws

✖ 1 problem (1 error, 0 warnings)

ESLint Config

{
  "plugins": ["jsdoc"],
  "parserOptions": {
    "ecmaVersion": 2017
  },
  "rules": {
    "jsdoc/require-throws": 2
  }
}

ESLint sample

/**
 */
async function foo() {
  throw Error("bar");
}

Environment

• Node version: 14.16.1
• ESLint version: 7.25.0
• eslint-plugin-jsdoc version: 33.0.0

[brettz9]

A function with the async keyword will never be able to have throws, but I think it is meaningful to have a means of documenting the types that are rejected.

FWIW, TypeScript assumes "any" type for the rejected value, even while allowing the resolved value to be specified. Barring such a convention for specifying the rejected value, I think we need to allow for a means of requiring that the rejected value be documented.

There could admittedly be ambiguity in functions which are only async in having an @async tag, but which are regular functions which may throw synchronously as well as perform some async behavior (which may reject), but without a convention, I think it is better for this function to require the error types be documented, and consumers will just have to know that "throws" here refers to the rejection type given that the function is async.

We could potentially add config to prevent this, however.

[gajus]

🎉 This issue has been resolved in version 35.3.2 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀