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

Question

给定以下代码，当我们调用baz函数时，自动补全将显示'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) => {
  ...
};

Where House是一个React组件，根据颜色和位置属性渲染一个房子。

而这个House组件在整个项目中都被广泛使用。

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

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

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

我想要的是这样的： 附言：我知道我可以将paintColor和locations转换为枚举，并使用类似这样的东西：

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

但是那个组件接口并不像我的原始提案那样好。

- davidx1

---

你正在创建一个由字符串联合组成的类型。你打算如何注释该联合中的每个基本字符串？下面的重载建议非常好。 - joshstrike

Answer 1

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

解决方案 #1：函数重载

/**
 * 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;
}

截图

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

- Karol Majewski

---

谢谢您的建议。不幸的是，它们并不完全符合我的需求。我已经编辑了原始问题，以便更好地说明我正在尝试做什么以及为什么这样做。也许您有更好的想法来完成这些事情？ - davidx1

Answer 2

这是TypeScript的一个当前行为限制（不确定是否在待办事项中）。例如，可以查看TypeScript存储库中的此问题票证，该问题涉及联合类型中的字符串字面量：支持解析TSDoc字符串注释＃38106。给该问题票证点个赞并订阅它，以便获取有关讨论和进展的通知（但请避免像“+1”/“bump”/“me too”这样的嘈杂评论）。

还可以查看TSDoc存储库中的相关问题票证：RFC：指定简单联合类型上允许使用文档注释＃164，以及typedoc存储库中的此问题票证：支持类似枚举的字符串字面量类型的使用＃1710。

如果您想要枚举值的悬停信息，那么您可以通过切换到使用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];

当你将鼠标悬停在"Foo.a"中的"a"上时，会出现一个悬停小部件，其中包含"AAA"。

- starball