Question about type definitions

[jsumners-nr]

In jsdoc type definitions are picked up regardless of the file they are defined in. Consider:

foo.js

'use strict'

/**
 * Foo is an interface not a class.
 *
 * @interface
 * @private
 */
class Foo {
  /**
   * The name of the thing.
   *
   * @type {string}
   */
  name
}

module.exports = Foo

bar.js

'use strict'

/**
 * Bar is a Foo
 *
 * @extends Foo 
 */
class Bar extends Foo {
  /**
   * The answer to everything.
   *
   * @type {number}
   */
  answer = 42

  constructor() {
    super()
    this.name = 'Bar'
  }
}

module.exports = Bar

Running jsdoc -p *.js on the above will result in an out/index.html that shows a Bar definition that links back to Foo:

But if we have the jsdoc/no-undefined-types rule enabled for this eslint plugin we will get an error in bar.js about Foo being undefined. I think https://github.com/gajus/eslint-plugin-jsdoc/issues/99 is discussing this same problem, but I'm not clear what the resolution is. Are we able to configure this plugin to work as jsdoc does?

[brettz9]

ESLint lints one file at a time, so if you don't import the variables (e.g., by using ESM), it won't be aware of them.

So the no-undefined-types rule is indeed limited. You can disable this particular rule or use an ESLint disable directive to suppress individual errors, if you wish.

jsdoc, the tool, defined a popular syntax which has since become refined by TypeScript. One can use TypeScript-flavored jsdoc within plain JavaScript without need for TypeScript syntax (using the allowJs and optionally checkJs tsconfig.json options). The original jsdoc project has been fairly stagnant in terms of updating its syntax, and since there are other tools such as typedoc which work with (TypeScript-flavored) jsdoc syntax as well, I would personally recommend projects go the TypeScript-flavored jsdoc route. One can express types more readily, as well as export types such that other projects can benefit from Intellisense auto-complete and tooltips which display the types.

[jsumners-nr]

So the no-undefined-types rule is indeed limited. You can disable this particular rule or use an ESLint disable directive to suppress individual errors, if you wish.

Thank you. That's what I expected to be the case.

jsdoc, the tool, defined a popular syntax which has since become refined by TypeScript. One can use TypeScript-flavored jsdoc within plain JavaScript without need for TypeScript syntax (using the allowJs and optionally checkJs tsconfig.json options). The original jsdoc project has been fairly stagnant in terms of updating its syntax, and since there are other tools such as typedoc which work with (TypeScript-flavored) jsdoc syntax as well, I would personally recommend projects go the TypeScript-flavored jsdoc route. One can express types more readily, as well as export types such that other projects can benefit from Intellisense auto-complete and tooltips which display the types.

This does not seem relevant to the question asked. In particular, it does not apply to JavaScript projects.

[brettz9]

It does apply to JavaScript projects. TypeScript tooling and documentation generation can be used with plain JavaScript. That's what I was talking about with the allowJs option.