如何为@typedef定义的对象内方法编写JSDoc文档？

针对你在为lufthansa对象的book方法编写JSDoc时遇到的困惑，这里给出两个可行的正确写法，解决参数隐式any的类型提示问题：

方案一：拆分类型定义+方法级详细注释 #

先抽离方法的返回值类型到BookMethod，再在对象的book方法上补全参数注释和功能说明，兼顾类型定义和可读性：

/**
 * @typedef {function(number, string): boolean} BookMethod
 */

/**
 * @typedef {Object} Airline
 * @property {string} name - 航空公司名称
 * @property {BookMethod} book - 航班预订方法
 */

/** @type {Airline} */
const lufthansa = {
  name: 'Lufthansa',
  /**
   * 为乘客指定航班号完成预订
   * @param {number} flightNum - 目标航班的数字编号
   * @param {string} passengerName - 预订乘客的姓名
   * @returns {boolean} 预订操作是否成功
   */
  book(flightNum, passengerName) {
    console.log(`已为${passengerName}预订航班${flightNum}`);
    return true;
  }
};

这种写法的优势是：既通过Airline typedef统一了对象结构，又能在方法本身添加更具体的业务注释，同时VSCode能准确识别参数类型，不会触发隐式any的提示。

方案二：完整typedef方法类型+显式绑定方法类型 #

如果想在BookMethod里统一定义参数和返回值类型，需要在book方法上显式用@type绑定类型，让VSCode自动关联参数类型：

/**
 * @typedef {function(flightNum: number, passengerName: string): boolean} BookMethod
 */

/**
 * @typedef {Object} Airline
 * @property {string} name - 航空公司名称
 * @property {BookMethod} book - 航班预订方法
 */

/** @type {Airline} */
const lufthansa = {
  name: 'Lufthansa',
  /** @type {BookMethod} */
  book(flightNum, passengerName) {
    console.log(`已为${passengerName}预订航班${flightNum}`);
    return true;
  }
};

原第二种写法报错的原因 #

你之前的写法里，虽然Airline typedef指定了book的类型，但JS是动态类型语言，VSCode无法自动将对象方法的参数和typedef里的参数类型做关联，必须通过@type显式绑定，或者直接在参数上添加JSDoc类型注释，才能消除隐式any的提示。

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