How to add description to a property type, so that intellisense shows it in VSCode

Question

I am trying to create a reusable type, that is present as arguments a few functions. But intellisense only shows descriptions added to interfaces and not the original type declaration.

So, why this Prop1 description is shown.

but my formattedString description (/** Use this format: xx-xxxx-xxx */) is not? Even thought intellisense catched the SomeFormatedString definition.

/** Use this format: xx-xxxx-xxx */
export declare type SomeFormattedString = string

export declare interface SomeInterface {
  /** bla bla 1 description. */
  bla1?: boolean;
  /** bla bla 2 description. */
  bla2?: boolean;
}

export declare interface MyFunctionParams {
  /** Prop1 description. */
  prop1?: string;
  /** Prop2 description. */
  prop2?: string;
  someInterface: SomeInterface;
  formattedString: SomeFormatedString;
}

Answer 1

The issue here seems to be that they're documentation strings for two separate things. formattedString is a property of an object whose description may vary from the description of its expected type (SomeFormattedString). For example:

export declare interface MyFunctionParams {
  // ...

  /** The user's UUID
  xx-xxxx-xxx */
  formattedString: SomeFormatedString;
}

By using the documentation string of the type itself, it loses context. Now, imagine we had some sort of union type (e.g. SomeFormatedString | SomeInterface) and both have their own documentation strings. How do you determine which documentation string to show? Do you show both with a horizontal rule? What happens when you have 8 different types in a union, each with their own lengthy description?

Consider adding a description to the property itself telling the user how the property is used.

As a side note, the declare keyword is used to tell TypeScript that a variable it cannot see is defined. Since you're defining these interfaces and types here, that's a few extra characters you don't have to type ;)