[英]How to do TypeScript tsdoc documentation for function argument with generic type that extends an interface?
Consider the following code, note the documentation of someField
:考虑以下代码,注意someField
的文档:
interface Test {
/**
* Some description.
* lorum ipsum.
* foo bar.
*/
someField: string;
}
function withGeneric<T extends Test>(arg: T) {
return arg;
}
function withoutGeneric(arg: Test) {
return arg;
}
withGeneric({
someField: ""
});
withoutGeneric({
someField: ""
});
When I hover with my mouse over someField
in the withoutGeneric
call, VSCode nicely shows me the documentation:当我悬停我的鼠标someField
在withoutGeneric
通话,VSCode很好地显示我的文档:
However, when hovering over someField
in the withGeneric
call, the documentation is not shown:但是,在withGeneric
调用someField
悬停在someField
时,不会显示文档:
Is there a way to make the tsdoc documentation work with the generic argument too?有没有办法使 tsdoc 文档也与通用参数一起使用?
Consider that when you create the inline object, it is not typed as Test
:考虑到当您创建内联对象时,它的类型不是Test
:
const config = {
someField: ""
};
Your withoutGeneric
function, by definition, takes a Test
-typed argument, so TypeScript can infer the property types.根据定义,您的withoutGeneric
函数采用Test
类型的参数,因此 TypeScript 可以推断属性类型。 However, when your function is generic but you don't explicitly set the generic type then TypeScript will infer the generic type from the inline object's type, which is just the default inferred type you can see above.但是,当您的函数是泛型但您没有显式设置泛型类型时,TypeScript 将从内联对象的类型推断泛型类型,这只是您在上面看到的默认推断类型。
You can see this in the intellisense:您可以在智能感知中看到这一点:
TypeScript is inferring the generic type as { someField: string; }
TypeScript 将泛型类型推断为{ someField: string; }
{ someField: string; }
. { someField: string; }
. This satisfies the requirements of the Test
interface, but the value is its own inferred default type, not Test
.这满足了Test
接口的要求,但是值是它自己推断的默认类型,而不是Test
。
Consider the following example:考虑以下示例:
interface Foobar {
/**
* Unrelated doc string
*/
someField: string;
}
const config:Foobar = {
someField: ""
}
You get the following intellisense:您将获得以下智能感知:
Note that the withGeneric
function is satisfied by the Foobar
type because it has the required properties and they are of the correct type.请注意, Foobar
类型满足withGeneric
函数,因为它具有所需的属性并且它们是正确的类型。 However, the doc string associated with someField
would be Unrelated doc string
because that is the type of the config
variable.但是,与someField
关联的文档字符串将是Unrelated doc string
因为这是config
变量的类型。
If you explicitly set the generic type of your function, then it will behave as you expected.如果您显式设置函数的泛型类型,那么它会按您的预期运行。
withGeneric<Test>({
someField: ""
});
Yields the following:产生以下结果:
If you explicitly set the type to Foobar
, then you'll get Foobar's doc strings:如果您明确地将类型设置为Foobar
,那么您将获得 Foobar 的文档字符串:
withGeneric<Foobar>({
someField: ""
});
yields:产量:
I found an answer that works for my purpose.我找到了一个适合我的目的的答案。 Add a union with the extended from type:添加具有扩展自类型的联合:
/**
* withGeneric sample
* @typeParam T - must be a Test
* @param arg
* @returns
*/
function withGeneric<T extends Test>(arg: T & Test) {
return arg;
}
Now VSCode does show the documentation:现在 VSCode 确实显示了文档:
It feels like a trick, but I fail to see any disadvantages to it?感觉就像一个把戏,但我看不出它有什么缺点?
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.