JSDoc 重载函数不适用于 TypeScript

Question

我正在使用其他问题和在线建议的 JSDoc 重载语法，不确定我是否正确，但这里是：

/**
 * @param {string} param
 * @returns {'string result'}
 *//**
* @param {number} param
* @returns {'number result'}
*/
function overloaded(param) {
  switch (typeof param) {
    case 'string': return 'string result';
    case 'number': return 'number result';
  }

  throw new Error(`Invalid type: ${typeof param}`);
}

overloaded('seven');
overloaded(7);

string result如果输入参数的类型为 ，则此函数应准确返回，如果输入参数的类型为string，则应number result准确返回number。在普通的 TypeScript 中，这将是：

function overloaded2(param: string): 'string result';
function overloaded2(param: number): 'number result';
function overloaded2(param: string | number): 'string result' | 'number result' {
switch (typeof param) {
    case 'string': return 'string result';
    case 'number': return 'number result';
}

throw new Error(`Invalid type: ${typeof param}`);
}

overloaded2('seven');
overloaded2(7);

问题是我所拥有的 JSDoc 可能是不正确的，因为 VS Code 语言服务提供的 TypeScript 推理无法获取重载：

基本上它只看到第一个重载。TypeScript 中的 JSDoc 支持是否足够先进，以至于我能够将 JavaScript 代码输入到与 TypeScript 对应的程度相同的程度？那会怎样？

Answer 1

TypeScript 5 将有一个新@overload标签，允许您执行此操作：

/**
 * @overload
 * @param {string} param
 * @returns {'string result'}
 *
 * @overload
 * @param {number} param
 * @returns {'number result'}
 *
 * @param {string | number}
 */
function overloaded(param) {
  // ...
}

查看此博客文章了解更多详细信息：

https://devblogs.microsoft.com/typescript/announcing-typescript-5-0-beta/#overload-support-in-jsdoc