require-returns-check should have option to accept just one return (for Typescript)

[noahtallen]

Expected behavior

The following function should not have any jsdoc errors:

/**
 * @param x A useful param.
 * @returns A useful string.
 */
function foo( x: boolean ): string | undefined {
	if ( x ) {
		return 'bar';
	}
}

It's typescript code, which means that types aren't encoded in the jsdoc @returns tag. You can solve this by putting @returns {string|undefined}, which isn't valuable (though it would be valuable for JS functions), or by adding return to the very end, which also isn't valuable.

Is this a bug or expected behavior? If it is expected behavior, I think the default rule shouldn't require empty return tags for this scenario!

While this can also happen for JS code, I think it's somewhat useful, in that it forces you to put the correct type beside @returns if the function doesn't always return something. But that's already covered by typescript.

Actual behavior

This error occurs:

JSDoc @returns declaration present but return expression not available in function

ESLint Config

'jsdoc/require-returns-check': 'error'

ESLint sample

See above

Environment

• Node version: happens in both 16 and 18
• ESLint version: 8.14.0
• eslint-plugin-jsdoc version: 39.6.6 (latest)

[brettz9]

TypeScript support was secondary to this project, and indeed what you report is the desired behavior, at least for non-TypeScript mode. However, we have come to support TypeScript more fully and would welcome a new option or configuration to do as you have requested.

See my comment at #932 (comment) for more background (though we can now track this request in this issue).

[noahtallen]

That does sound really useful. For us, we came across this issue just by updating the package without making other changes

[brettz9]

Yes, as mentioned in the comment, the reason there was not an issue before is because it was really a bug that got fixed, at least in how we wanted the rule.

[brettz9]

Rather than detecting "typescript" mode to enable this feature, I'm thinking we might just detect if a type is undefined, and in such a case, only check for one path to a return. We already have the require-returns-type rule to check for missing types, and I'd rather we keep typescript mode confined to the JSDoc flavor used by TypeScript rather than making assumptions such as that all TS users don't want to define types (one can check plain JS+JSDoc files using TS too).

[noahtallen]

That seems fair to me, since we'd be enforcing type information outside of JSDoc in this case anyways

[brettz9]

And sorry by "detect if a type is undefined", I should have said "detect if a type is absent". If a type is undefined, the same behavior would apply.