Don't require @returns when an async function is returning a Promise (require-returns)

[yvele]

This function is returning a Promise and is already defined as async:

/**
 * @param {array} a
 */
async function foo(a) {
  return Promise.all(a);
}

I get the following error:

Missing JSDoc @returns declaration

That doesn't make any sense.. all async functions are "returning" a Promise anyway... I don't want to add an anemic @returns {Promise} declaration. This is redundant with async anyway.

Is it possible to handle this use case?

Note that the legacy native ESLint JSDoc rule was handing this use case

[brettz9]

Yes, this was a bug. Fixed by 13f5533 (version 18.4.4).

There had been some refactoring which removed the async checks. As of the fix just now, you should only see this error if setting the forceReturnsWithAsync option.

FWIW, the utility of using this latter option (as with forceRequireReturn though that will always apply regardless of whether the function is async or not) is if you wish to always reflect to other developers that consideration was given to the intended return value.

Another utility is in conjunction with settings.jsdoc.preferredTypes. If you set up Promise types to report when there is no resolved value, i.e., if you've set settings.jsdoc.preferredTypes.Promise without a replacement, in such a case, developers will be forced to document not only that a type was returned, but, if they indicate it was a Promise, to also indicate to which type that Promise resolves.

Closing, but feel free to comment further as needed.

[brettz9]

There is no checking done, however, to ensure that if a type is specified for an async function that it is always a Promise (or say a custom type which extends Promises), so if a developer says that the return type for an async function was a number, there is no rule to report that this should instead be Promise<number>.