搜索词
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, RethrowCallback
nise和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