Is there a way to document fields in an interface in TypeScript?

Question

Say I have the following:

interface Validator {
  validate: (value: string) => boolean;
  errorMessage: string;
}

interface EditDialogField {
  label: string;
  prop: string;
  required?: boolean;
  type: 'input';
  validators?: Validator[];
}

This is useful, as IntelliSense pops up suggestions when I use these interfaces, but I'd like the ability to add comments that also show up in IntelliSense (specifically VS Code). Is this possible?

Possible duplicate of [Where is the syntax for TypeScript comments documented?](https://stackoverflow.com/questions/23072286/where-is-the-syntax-for-typescript-comments-documented) — Matt McCutchen, Aug 01 '18 at 19:58

score 95 · Accepted Answer · answered Aug 01 '18 at 20:01

95

Got it!

interface EditDialogField {
  /** Explain label here */
  label: string;
  /** Explain prop here */
  prop: string;
  required?: boolean;
  type: 'input';
  validators?: Validator[];
}

answered Aug 01 '18 at 20:01

ffxsam

26,428
32
94
144

Can you please confirm if it works with `//` only? I guess `/**` is the only valid syntax? – Eric Burel Nov 26 '20 at 08:18
2

can confirm this works in VSCode, but couldn't find it documented on https://tsdoc.org – mb21 Dec 26 '20 at 09:22
`/** comment */` DOES show up in intelliJ IDEA when Editor > Appearance > Show documentation popup is checked. – rushkeldon Apr 21 '21 at 20:29
What setting in VSCode enables those to show as hover hint? – johnborges Jan 19 '22 at 19:01

Ronan Quillevere · Answer 2 · 2020-08-21T08:19:49.640

33

If you want to see it appearing when your mouse is hover in your editor, I suggest you document the interface and use the @field inside the documentation comment.

Alternatively you could use @member maybe that gives a better syntax-highlighting for the doc

/**
 * This is the description of the interface
 *
 * @interface EditDialogField
 * @member {string} label is used for whatever reason
 * @field {string} prop is used for other reason
 */
interface EditDialogField {
  label: string;
  prop: string;
  required?: boolean;
  type: 'input';
  validators?: Validator[];
}

Result inside VSCode

edited Aug 21 '20 at 08:19

answered Aug 20 '20 at 13:25

Ronan Quillevere

3,699
1
29
44

I see it when I hover over the interface. However, when I hover over the destructured vars when I use it the information does not appear. However, using @ffxsam approach shows the information when hovering destructured vars but not over the interface. – kiril Sep 27 '22 at 09:27
1

Could you link to documentation legitimizing these tags? I don't see them in [TSDoc](https://tsdoc.org/); is there another standard? – Ed Noepel Apr 13 '23 at 17:18

score 4 · Answer 3 · answered Sep 27 '22 at 09:42

I want to build upon @Ronan Quillevere's and @ffxsam's answers.

Ronan's approach shows information in VSCode when hovering over the interface as shown in his comment.

However, when using that interface as in the following example, hovering over the destructured vars of the last line does not show the documentation from the member/field tag, but from the comment inside the interface, as ffxsam suggested.

/**
 * This is the description of the interface
 *
 * @interface EditDialogField
 * @member {string} label is used for whatever reason
 * @field {string} prop is used for other reason
 */
 interface EditDialogField {
  /** Doc inside the interface */ 
  label: string;
  prop: string;
  required?: boolean;
  type: 'input';
}

const dialog: EditDialogField = { label: 'label', prop: 'prop', type: 'input' };
const { label, prop } = dialog;

These pics better show the behavior in VSCode.

I'm not sure if there is way to unify this, but it would be great

Is there a way to document fields in an interface in TypeScript?

3 Answers3