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 #452 (comment).

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.