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?

Creel

Possible duplicate of Where is the syntax for TypeScript comments documented? – Enmesh

Answer 1

Got it!

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

Creel

Can you please confirm if it works with // only? I guess /** is the only valid syntax? – Peregrine

can confirm this works in VSCode, but couldn't find it documented on tsdoc.org – Slovakia

/** comment */ DOES show up in intelliJ IDEA when Editor > Appearance > Show documentation popup is checked. – Flashback

What setting in VSCode enables those to show as hover hint? – Schober

Answer 2

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

Mandeville

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 @Creel approach shows the information when hovering destructured vars but not over the interface. – Foreground

Could you link to documentation legitimizing these tags? I don't see them in TSDoc; is there another standard? – Subway

Answer 3

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

Foreground