Support for JSDoc interface definition

Search Terms

jsdoc, interface I found https://github.com/microsoft/TypeScript/issues/16142 which was closed by the reporter, and never reopened even though some other people suggested it.

Suggestion

JSDoc has a way to declare interfaces, through @interface, @function (and then @implements on the class). It would be great if tsc could support them (defining a TS interface based on that info).

Use Cases

JSDoc interfaces are useful to define interfaces implemented by multiple classes, that are then used based on this interface. This is part of JSDoc, but currently unsupported by tsc.

Examples

/**
 * @interface Metric
 */
/**
 * @function
 * @name Metric#getName
 * @returns {string}
 */
/**
 * @function
 * @name Metric#compute
 * @param context
 * @param [extra]
 * @returns {Promise<object>}
 */

/**
 * @constructor
 * @implements {Metric}
 */
function ActivityScoreMetric () {
    // [REDACTED]
}
ActivityScoreMetric.prototype = {
  compute: function (context, extra) {
      // [REDACTED]
  },

  getName: function () {
    return 'activity_score'
  }
}

// Other implementations go there

// Later code deals with `Array<Metric>` for some variables

Checklist

My suggestion meets these guidelines:

• This wouldn’t be a breaking change in existing TypeScript/JavaScript code
• This wouldn’t change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn’t a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript’s Design Goals.

[sandersn]

This is a sub-issue of https://github.com/microsoft/TypeScript/issues/30624. Right now we have decided not to make all of Typescript’s features available in JSDoc. Writing 40 lines of metadata in a comment is not much different from putting those same lines in a d.ts file, and we believe the d.ts syntax is much more readable to humans.

[TimvdLippe]

We use @interface extensively in Chrome DevTools and the lack of support with checkJs means we can not use TypeScript to check our JavaScript. Our usage: https://cs.chromium.org/search/?q=f:devtools-frontend+@interface&sq=package:chromium&type=cs

I am not sure if we can use the .d.ts trick, as TS itself complains about how classes annotated with @interface are defined (it complains about missing return statements for example)