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.

Start by running tsc against the issue's JSDoc example and reviewing how the compiler handles @interface, @function, @implements, and generic types. Define the expected behavior for the Metric interface, its methods, multiple implementations, and Array; done means the example is type-checked consistently without changing emitted JavaScript.