如何为属性类型添加描述以在VSCode IntelliSense中显示？为何自定义类型的注释无法被智能提示识别？

这是因为TypeScript的结构类型系统和VSCode IntelliSense的处理逻辑共同导致的：当你的类型别名只是基础类型（比如string）的直接别名时，TypeScript会将其视为与基础类型完全等价，VSCode的IntelliSense默认不会自动拉取类型别名本身的JSDoc注释，只会显示接口属性的类型信息（比如string）。而接口成员的注释能正常显示，是因为它们直接属于接口属性的定义，IntelliSense会优先读取这些关联的注释。

解决方案1：使用带品牌(Brand)的类型别名（推荐） #

这是最优解，既实现了类型复用，又能让IntelliSense正确展示类型别名的注释，还能额外提升类型安全性：

/** Use this format: xx-xxxx-xxx */
export type SomeFormattedString = string & { __brand: 'SomeFormattedString' };

// 创建该类型的示例值时，需要用类型断言
const validFormattedString: SomeFormattedString = "xx-xxxx-xxx" as SomeFormattedString;

现在当你悬停MyFunctionParams里的formattedString属性时，IntelliSense会清晰显示SomeFormattedString的类型定义以及对应的注释——因为这个类型不再是单纯的string，而是带有独特标识的"品牌类型"，TypeScript会将其视为独立的类型，不会和原始string混淆。

解决方案2：结合JSDoc的@typedef标签 #

如果你不想修改类型的结构，可以在TS类型别名上添加JSDoc的@typedef标签，引导VSCode关联类型别名的注释：

/**
 * Use this format: xx-xxxx-xxx
 * @typedef {string} SomeFormattedString
 */
export type SomeFormattedString = string;

这样VSCode的IntelliSense在识别接口属性类型时，会读取@typedef块中的注释内容，悬停时就能看到类型别名的描述。

解决方案3：在接口属性注释中显式引用（临时方案） #

如果上面的方案都不适用，你可以在接口属性的注释里重复类型别名的描述，或者用@see标签指向类型别名：

export declare interface MyFunctionParams {
  /** Prop1 description. */
  prop1?: string;
  /** Prop2 description. */
  prop2?: string;
  someInterface: SomeInterface;
  /** 
   * Formatted string field
   * @see SomeFormattedString
   * Use this format: xx-xxxx-xxx
   */
  formattedString: SomeFormattedString;
}

不过这种方式会导致注释重复，违背了复用类型注释的初衷，所以只建议作为临时应急方案。

内容的提问来源于stack exchange，提问作者apt