Forbid non-promise types in @return on async functions

[Daimona]

Motivation

async functions always return promises, and can never return anything else. Therefore, documenting an async function as @return {T} is always wrong, unless T is (a subtype of) Promise.

Current behavior

The existing rules do not flag those return tags as incorrect. This problem was also mentioned in https://github.com/gajus/eslint-plugin-jsdoc/issues/452#issuecomment-568454170.

Desired behavior

I would like to receive a warning if an async function is annotated as returning a non-promise. This could be part of an existing rule (presumably in the require-return* family) or a new rule. Either would work.

Alternatives considered

If checking for non-promises in general is too complicated, it would be great to at least check native types for the time being. So warn for @return {string}, @return {void} etc., but ignore @return {SomeCustomType}.

[juhort]

@Daimona Curious what your workflow is? I'm guessing you've js files with JSDoc comments and you're using TS to check the JSDoc comments.

AFAIU, the require-return* rules don't check if the types in JSDoc align with the types in the implementation. For eg., the following snippet has no complains from ESLint, although the return types clearly don't match.

/**
 *
 * @param {number} a - First number
 * @param {number} b - Second number
 * @returns {number} - Sum of a and b
 */
function add(a, b) {
    const result = a + b;
    return result.toString(); // Typed as `number` in JSDoc, but returns a `string`
}

const result = add(1, 2);
//    ^? const result: number

But if you've TS checking your js files, then TS would complain:

And TS would also complain if the return type for an async function is not wrapped in Promise, like:

So, this plugin is anyways not doing any type checking, it's just validating the presence of certain tags and description in JSDoc comments. Am I missing something?? Probably there's some other workflow that I'm not aware of, but I'm happy to learn.

[Daimona]

@Daimona Curious what your workflow is? I'm guessing you've js files with JSDoc comments and you're using TS to check the JSDoc comments.

No, we aren't using TS. We only use vanilla JS and, well, eslint for linting.

AFAIU, the require-return* rules don't check if the types in JSDoc align with the types in the implementation. [...] So, this plugin is anyways not doing any type checking, it's just validating the presence of certain tags and description in JSDoc comments. Am I missing something?? Probably there's some other workflow that I'm not aware of, but I'm happy to learn.

No, I don't think you're missing anything. I am simply proposing that, as an enhancement (i.e., new functionality), the plugin should warn when @return {NotAPromise} is used on an async function. Unlike checking whether the types in the JSDoc align with the implementation, my proposal can be implemented with no need for type inference of any kind. Especially if limited in scope to just forbidding native types, as described in "Alternatives considered".

[brettz9]

Are you aware that TypeScript can be used to check vanilla JavaScript? (the checkJs option).

[brettz9]

In any case, this wasn't too hard to add for async functions. See #1548. It could be done for other Promise-returning functions in theory, but would require more work.

[github-actions[bot]]

:tada: This issue has been resolved in version 60.7.0 :tada:

The release is available on:

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

Your semantic-release bot :package::rocket: