搜索词
jsdoc, interface
我找到了 #16142 ,它被报告者关闭了，即使有人建议，也从未重新打开。
建议
JSDoc 有通过 @interface , @function (然后在类上使用 @implements)声明接口的方法。如果tsc能支持它们(基于这些信息定义一个TS接口),那就太好了。
用例
JSDoc接口对于定义由多个类实现的接口非常有用，然后根据此接口进行使用。这是JSDoc的一部分，但目前不受tsc支持。
示例
/**
* @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检查清单
我的建议满足以下准则：
- 这不会对现有的TypeScript/JavaScript代码造成破坏性更改
- 这不会改变现有JavaScript代码的运行时行为
- 这可以在不根据表达式的类型发出不同的JS的情况下实现
- 这不是一个运行时特性(例如库功能、带有JavaScript输出的非ECMAScript语法等)
- 这个特性将与 TypeScript's Design Goals 的其他部分保持一致。
7条答案
按热度按时间lx0bsm1f1#
这是一个子问题，关于#30624。目前我们决定不在JSDoc中提供Typescript的所有功能。在注解中编写40行元数据与将这些相同的行放入d.ts文件没有太大区别，我们认为d.ts语法对人类来说更易读。
gab6jxml2#
我倾向于同意TS的语法更易读。但在这里，我不是要求支持在JSDoc中使用TS语法(这是我从#30624那里理解的),而是支持现有的JSDoc功能(这样已经在JSDoc中使用它们的代码可以被TS编译器理解)。这是一个现有的用于接口的JSDoc语法(是的，再次，我完全同意它比TS语法更不易读)。
ni65a41a3#
我通过在用户测试的依赖项中搜索
@interface和@implements来查找它们的用途。这是一段很好的JS代码片段。它看起来不像有人像jsdoc建议的那样使用@interface,尽管我发现有一些人像闭包那样使用它。除非我们有证据表明人们像jsdoc建议的那样使用
@interface,否则我们没有理由支持它。react-dom
用于
PooledClass的@implements,它被声明为一个没有jsdoc的var。在对象字面量上使用
@interface作为jsdoc。它总是引用一个看似超类的东西，所以我认为它们是用来表示@extends的。superagent
使用
@implements ReadableStream,但没有在任何地方定义该接口。ejs
与superagent相同，只是带有
Cache, EscapeCallback, RethrowCallbacknise和sinon
在一个没有实现的类上使用
@interface:我非常确定这就是闭包定义接口的方式。chrome-devtools-frontend、firebase和protobufjs也是这样工作的。这些都是谷歌的项目，所以这并不令人惊讶。
0qx6xfy64#
使用
@implements ReadableStream,但没有在任何地方定义该接口。ReadableStream是否在 nodejs 类型中定义？ubof19bj5#
我们在Chrome DevTools中广泛使用
@interface,而checkJs缺乏支持意味着我们无法使用TypeScript来检查我们的JavaScript。我们的用法：https://cs.chromium.org/search/?q=f:devtools-frontend+@interface&sq=package:chromium&type=cs我不确定我们是否可以使用
.d.ts技巧，因为TS本身对用@interface注解的类是如何定义的(例如，它抱怨缺少返回语句)表示不满。mwkjh3gx6#
TimvdLippe,您是否可以为支持闭包的
@interface打开一个单独的问题？它有以下不同之处：(1)受众不同；(2)需求不同；(3)实现方式不同。拥有一个单独的问题对于第(1)点很有用，因为我们使用投票数作为功能优先级的依据。但是基于d.ts的解决方法也是不同的；我想了解您目前尝试了哪些方法以及遇到的Typescript错误是什么。bqf10yzr7#
我们在Chart.js中使用
@interface。例如，为了记录我们的插件接口：https://github.com/chartjs/Chart.js/blob/771fe520957199b32a26205c14f4816002842bcb/src/core/core.plugins.js#L173