TypeScript中解构Math对象方法时如何保留原有注释提示

问题根因 #

TypeScript的类型推断逻辑仅会在函数赋值、对象解构时继承函数的类型签名，JSDoc注释不属于类型定义的组成部分，因此不会被自动携带到新的变量上，这是TypeScript类型系统的设计特性，并非VSCode或者TypeScript的bug。

解决方案 #

方案1：全局扩展Math对象（适合给原生Math方法补充/修改注释） #

如果你的核心需求是给原生Math对象的方法补充注释、或是新增自定义Math扩展方法，可以通过全局模块扩充的方式实现，修改后所有调用Math方法的位置都会显示你定义的注释：

// 写在项目内任意一个`.d.ts`声明文件，或者带`export {}`的ts文件中
declare global {
  interface Math {
    /**
     * 返回数字的自然对数（底数为e）
     * @param x 待计算自然对数的数值
     * @returns 数值的自然对数结果，若入参小于0则返回NaN
     */
    log(x: number): number;

    // 新增自定义扩展方法的注释也可以写在这里
    /**
     * 计算两个数的平方和
     * @param x 第一个数值
     * @param y 第二个数值
     * @returns x² + y² 的计算结果
     */
    sumOfSquares(x: number, y: number): number;
  }
}

// 必须加这行，否则TS会把文件识别为全局脚本而非模块，导致扩充失效
export {}

方案2：手动给解构/赋值的变量加JSDoc（适合少量变量的场景） #

如果只是个别场景需要把Math方法赋值给变量、同时保留注释，直接在变量声明前补充JSDoc即可：

// 直接赋值的写法
/**
 * 返回数字的自然对数（底数为e）
 * @param x 待计算自然对数的数值
 * @returns 数值的自然对数结果，若入参小于0则返回NaN
 */
const log = Math.log;

// 解构的写法同理
/**
 * 返回数字的自然对数（底数为e）
 * @param x 待计算自然对数的数值
 * @returns 数值的自然对数结果，若入参小于0则返回NaN
 */
const { log: mathLog } = Math;

方案3：封装自定义Math工具对象（适合频繁使用解构的场景） #

如果项目中需要大量使用Math方法的解构调用，可以自己封装一层带有完整注释的工具对象，后续解构这个自定义对象就能正常显示注释：

export const MyMath = {
  /**
   * 返回数字的自然对数（底数为e）
   * @param x 待计算自然对数的数值
   * @returns 数值的自然对数结果，若入参小于0则返回NaN
   */
  log: Math.log,
  /**
   * 计算以2为底的对数
   * @param x 待计算对数的数值
   * @returns 以2为底的对数结果，若入参小于0则返回NaN
   */
  log2: Math.log2,
  // 其他需要用到的Math方法按需补充
  pow: Math.pow,
  sqrt: Math.sqrt
}

// 后续直接解构MyMath即可保留注释
const { log, pow } = MyMath;

注意 #

目前TypeScript没有提供自动继承原对象JSDoc到解构/赋值后变量的特性，所有需要保留注释的场景都需要手动标注JSDoc。

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