使用JSDoc注释TypeScript工具类型是否被社区认可？

问题背景 #

下面是一个实现字符串拆分功能的TypeScript工具类型Split，这类递归类型对新手来说可读性较差：

type Split<
  S extends string, 
  D extends string, 
  T extends string[] = []
> = 
 S extends `${infer BD}${D}${infer AD}` 
 ? Split<AD, D, [...T, BD]> 
 : [...T, S];

为了提升可读性，我给它添加了JSDoc注释：

/**
 * 将字符串类型按指定分隔符拆分为元组类型
 *
 * @param S - 要拆分的输入字符串类型
 * @param D - 用于拆分的分隔符字符串类型
 * @param T - 存储拆分结果的累加数组（可选，内部使用，无需手动传入）
 *
 * @example
 * // 拆分逗号分隔的字符串
 * type Result = Split<"apple,banana,cherry", ",">;
 * // Result: ["apple", "banana", "cherry"]
 */
type Split<
  S extends string, 
  D extends string, 
  T extends string[] = []
> = 
 S extends `${infer BD}${D}${infer AD}` 
 ? Split<AD, D, [...T, BD]> 
 : [...T, S];

想请教：这种给工具类型加JSDoc的做法是否被社区接受？是否存在潜在弊端？

回答 #

社区接受度 #

• 完全被接受，甚至是推荐做法。TypeScript官方文档明确鼓励给复杂的类型定义添加注释，尤其是工具类型这类抽象性强、依赖类型推断/递归逻辑的代码，JSDoc能快速帮使用者理解类型的用途、参数含义和正确用法，大幅降低上手门槛。
• 众多知名开源项目（比如TypeScript内置的标准库、utility-types这类工具库）都在工具类型中使用JSDoc注释，社区普遍认可这种提升代码可维护性的行为。

潜在弊端 #

• 冗余与误导风险：如果注释表述不准确，可能误导使用者。比如若没说明T是内部递归用的累加器、无需手动传入，新手可能会误以为必须传这个参数。
• 维护成本增加：当工具类型的逻辑更新时，必须同步更新JSDoc注释，否则会出现注释与代码行为不符的情况，反而造成理解混乱。比如后续修改Split让它支持空分隔符，却没更新注释，会让使用者误以为不支持该特性。
• 规范不统一：目前TypeScript对类型参数的JSDoc注释没有强制统一的标签规范，比如有的开发者习惯用@typeparam而非@param来标记类型参数，不过这只是团队协作层面的小问题，只要内部统一规范即可。

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