0

I'm having an interface from a 3rd party library (A). I'm creating an alias bar for a property foo in my project. This works fine, but I also want my alias to inherit the DocBlock comment of the property.

interface A {
  /**
   * It's a number
   */
  foo: number;
}

interface B extends A {
  bar: A["foo"];
}

const x: B = {
  foo: 1,
  bar: 2
};

In Codesandbox you can try this using CTRL+Hover inside x on foo and bar. foo will have comments, bar do not. I want bar also to show the same DocBlock comment.

https://codesandbox.io/s/lucid-architecture-6ppe6?file=/src/index.ts

wintercounter
  • 7,500
  • 6
  • 32
  • 46
  • Perhaps the `@see` directive coming in Typescript 4.1 may help you? https://devblogs.microsoft.com/typescript/announcing-typescript-4-1-beta/#jsdoc-see-tag – Alex Wayne Nov 17 '20 at 21:53

2 Answers2

1

The only answer here is that it just does not work that way. And for good reason. It's perfectly valid to use types to construct other types, but it's not necessarily valid to re-use documentation the same way.

Imagine you mention the name of this property in the documentation. (Which is very common)

interface A {
  /**
   * The foo property is a count of the number of foos.
   */
  foo: number;
}

Would you then expect to see this?

enter image description here

I would argue that's pretty confusing. As you use the type in other contexts, what it means in those contexts may change, and the documentation should be relevant to that context.

Instead I would argue that the docs for bar would be different. Something like:

interface B extends A {
  /**
   * bar is the same type as A.foo and is set during initialization.
   * It serves as a snapshot of the count of foos at the time this object was created.
   */
  bar: A["foo"];
}

For these reasons documentation is looked up by the how that interface or property is declared, and not the type assigned to it. It may have the same type, but why it's there and how it's used is very likely to be different.

Alex Wayne
  • 178,991
  • 47
  • 309
  • 337
0

I'm 90% sure this question is not related to typescript compiler itself. Since, TypeScript has structural type system, bar: A["foo"]; will be treated as bar: number. Hence, TS unable to bind A['foo'] with A interface. A['foo'] is an alias here, nothing more, nothing less.

You should add comment to bar: A["foo"]; directly.

I think it is better to raise an issue in VSCode/Your favourite IDE repo

captain-yossarian from Ukraine
  • 31,174
  • 3
  • 30
  • 62