no-undefined-types: false positives inside functions for type parameters declared by template tags

[snowteamer]

Expected behavior

No error.

Actual behavior

7:0 error The type 'T' is undefined jsdoc/no-undefined-types

ESLint Config

{
	"env": {
		"es6": true
	},
	"parserOptions": {
		"ecmaVersion": 2020,
		"sourceType": "module"
	},
	"plugins": ["jsdoc"],
	"root": true,
	"rules": {
		"jsdoc/no-undefined-types": "error"
	},
	"settings": {
		"jsdoc": {
			"mode": "typescript"
		}
	}
}

ESLint sample

/**
 * @template T
 * @param {T} arg
 */
function example(arg) {

	/** @param {T} */
	function inner(x) {
	}
}

Environment

• Node version: v14.1.0
• ESLint version: v7.1.0
• eslint-plugin-jsdoc version: 27.0.0

[wycats]

I hit this same issue with this reproduction:

class {
  /**
   * @template {object} T
   * @param {(node: QDigestNode) => T} callback
   * @returns {T[]}
   */
  map(callback) {
    /** @type {T[]} */
    let vals;
    vals = [];
    this.forEach((node) => vals.push(callback(node)));
    return vals;
  }
}

[snowteamer]

This error apparently also occurs when the type parameter is referenced inside the function by using other TypeScript-supported tags like @type instead of @param:

/**
 * @template T
 * @param {T} arg
 * @returns {[T]}
 */
function genericFunctionExample(arg) {
	const result = /** @type {[T]} */ (new Array());
	result[0] = arg;
	return result;
}

[snowteamer]

@brettz9 Regarding the scope of template tags, I could find some docs at
https://github.com/google/closure-compiler/wiki/Generic-Types#declaring-a-generic-type, I hope it helps

Otherwise, from my experience using TypeScript with JsDoc,
I think template type names defined in the JsDoc comment of a function can be used:

• anywhere in that comment (which is already supported by jsdoc/plugin),
• in any TS-supported tag (mainly @type, @param, @returns) attached to any AST node belonging to that function.

[brettz9]

Thank you for the reports and helpful information.

While I got some of the more low-hanging fruit by fixing the first problem case (with a nested function), fixing the other cases would seem to require creating our own scope detection based on following the AST parent chain. (ESLint's scopeManager.acquire(node) doesn't seem to get enclosing scopes for non-functions as we need.)

This is not currently something on my priority list (unless I may be able to get to it in the course of hopefully addressing #99 at some point), but PRs would be welcome.

[gajus]

🎉 This issue has been resolved in version 37.5.1 🎉

The release is available on:

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

Your semantic-release bot 📦🚀