如何用JSDoc注释工厂函数g3.Class所用的自定义对象g3.hybrid？

我之前也碰到过类似的JSDoc识别非标准继承模式的坑，针对你用g3.Class工厂函数基于g3.hybrid生成类但JSDoc识别不了父对象成员的问题，给你几个实用的解决思路：

1. 给父对象g3.hybrid补全类型定义注释 #

因为g3.Class这种自定义工厂函数的继承逻辑不是标准ES6 Class语法，JSDoc没法自动推断父对象的结构。你需要手动给g3.hybrid添加@typedef注释，明确它的所有属性和方法：

/**
 * 定义g3.hybrid的类型结构
 * @typedef {Object} G3Hybrid
 * @property {string} exampleProp - 父对象的示例属性说明
 * @method exampleMethod - 父对象的示例方法说明
 * @param {string} input - 方法的输入参数
 * @returns {void} 方法返回值说明
 */
// 用@type把g3.hybrid和定义好的类型绑定
g3.hybrid = /** @type {G3Hybrid} */ ({
  exampleProp: 'defaultValue',
  exampleMethod: function(input) {
    console.log(input);
  }
});

2. 在子类注释中关联父类型 #

当你用g3.Class生成子类时，通过@augments（或@extends）注释告诉JSDoc这个子类继承了G3Hybrid的成员：

/**
 * 基于g3.hybrid生成的自定义子类
 * @class
 * @augments G3Hybrid
 */
const MyCustomClass = g3.Class(g3.hybrid, {
  // 子类的自定义属性和方法
  customMethod: function() {
    // 这里调用父对象的exampleMethod，JSDoc就能识别了
    this.exampleMethod('test');
  }
});

3. 检查JSDoc配置文件的有效性 #

你执行命令时用了conf-1.json，可以确认几个点：

• 配置中有没有正确包含g3hybrid-1.js所在的文件路径，避免JSDoc漏解析父对象的定义
• 确保JSDoc版本是v3.6.0以上，旧版本对自定义类型的支持有限
• 如果需要解析复杂的继承逻辑，可以尝试启用JSDoc的plugins/closure插件（在配置的plugins数组中添加）

4. 用@borrows手动关联父对象成员 #

如果上面的方法还是没生效，可以用@borrows把父对象的成员“借”到子类的注释中，强制JSDoc识别：

/**
 * 自定义子类
 * @class
 * @borrows g3.hybrid.exampleProp as #exampleProp
 * @borrows g3.hybrid.exampleMethod as #exampleMethod
 */
const MyCustomClass = g3.Class(g3.hybrid, {
  // ...
});

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