为 Typescript 联合类型编写更具描述性的智能感知文档

Question

给定以下代码，当我们调用baz function 时，预先输入将显示 'a' 和 'b' 作为可能的值。

但是，如果我想为每个值提供额外的文档，我该怎么做呢？ 例如，如果需要这样的行为：

我想我应该提供更多有关我正在尝试做的事情以及原因的背景信息：

考虑以下示例：

const paintColor = {
  /** This color is good fo X */
  Waltz: "#d9e5d7",
  /** This color is good fo Y */
  "Indiana Clay": "#ed7c4b",
  /** This color is good fo Z */
  Odyssey: "#575b6a"
};

const locations = {
  /** There are no good school at this location*/
  City: "123 city center road",
  /** There are lots of parking at this location but it is very far*/
  West: "245 some other road"
};

interface HouseProp {
  color: keyof typeof paintColor; //"Waltz" | "Indiana Clay" | "Odyssey"
  location: keyof typeof locations; //"City" | "West"
}

const House = ({ color, location }: HouseProp) => {
  ...
};

其中 House 是一个 React 组件，它根据颜色和位置道具渲染房屋。

而这个House组件在整个项目中无处不在。

使用当前设置，我可以像这样使用 House：

<House color="Indiana Clay" location="City" />

问题是，IntelliSense 无法识别我作为代码的一部分编写的文档：

我想要的是：

PS 我知道我可以将paintColor和 locations 变成枚举，并使用这样的东西：

import House, {HouseColor, HouseLocation} from './House';
<House color={HouseColor["Indiana Clay"]} location={HouseLocation.City} />

但是那个组件界面并不像我最初的建议那么好。

Answer 1

你不能真正注释工会成员。 然而，你可以用不同的方式表达你的联合——通过使用重载或选择使用枚举来代替。

解决方案 #1：Function 过载

/**
 * a is good fo X
 */
function baz(param: 'a'): number;
/**
 * b is an excellent choice for Y
 */
function baz(param: 'b'): number;
function baz(param: 'a' | 'b'): number {
  return 1;
}

截屏

解决方案#2：作为接口重载

interface Baz {
  /**
   * a is good fo X
   */
  (param: 'a'): number;
  /**
   * b is an excellent choice for Y
   */
  (param: 'b'): number;
}

const baz: Baz = (param: 'a' | 'b') => {
  return 1;
}

截屏

解决方案#3：改用枚举

enum Foo {
  /**
   * a is good fo X
   */
  A = 'a',
  /**
   * b is an excellent choice for Y
   */
  B = 'b',
}

function baz(param: Foo) {
  return 1;
}

截屏

我知道这不是您想要的，但这是您的第二好的选择。

Answer 2

这是 TypeScript 的当前行为限制（不确定它是否在积压中）。 例如，请参阅 TypeScript 存储库中的这个问题单，它是关于联合类型中的字符串文字：支持解析 TSDoc 字符串注释#38106 。 给那张问题票竖起大拇指并订阅它以获得有关讨论和进展的通知（但请避免像“+1”/“bump”/“我也是”这样的嘈杂评论）。

另请参阅 TSDoc 存储库中的此相关问题单： RFC：指定允许对简单联合类型进行文档注释#164 ，以及类型文档存储库中的此问题单：支持类似枚举的字符串文字类型的使用#1710 。

如果你想要枚举值的 hover 信息，那么你可以通过切换到使用 TypeScript 的enum功能来解决它（这个问题的提问者已经指定他们不想这样做，但我发现仍然值得一提）。 前任。

/** FOO */
enum Foo {
   /** AAA */
   a = "a",
   /** BBB */
   b = "b",
   /** CCC */
   c = "c",
};
type FooArray = Foo[];

const foo = Foo.a;
const fooArray: FooArray = [Foo.a, Foo.b, Foo.c];

然后，当您 hover 将鼠标悬停在“ Foo.a ”中的“ a ”上时，您将看到一个带有“AAA”的 hover 小部件。