如何用JSDoc文档化函数混合生成的类及继承方法

这个问题在处理JS的mixin（尤其是这种高阶类工厂模式的）时真的很常见，JSDoc默认对这种动态生成的类结构支持确实不太友好，我来给你一步步搞定：

1. 先给SomeMixin本身补全正确的JSDoc标注 #

你的Mixin是一个返回类的函数，得明确告诉JSDoc它的输入输出，还要定义它提供的方法接口：

// SomeMixin.js
/**
 * 给目标类添加`func`方法的Mixin
 * @template T
 * @param {new () => T} superclass - 要被Mixin扩展的父类
 * @returns {new () => T & SomeMixinInterface} 带有Mixin方法的扩展类
 */
export default superclass => class SomeMixin extends superclass {
  /**
   * Mixin提供的示例方法
   */
  func() {}
};

/**
 * 定义SomeMixin添加的方法集合的接口
 * @interface SomeMixinInterface
 */
/**
 * @function func
 * @memberof SomeMixinInterface
 * @instance
 */

这里用@template做泛型处理，让JSDoc能追踪传入父类和返回子类的继承关系；用@interface把Mixin的方法单独抽出来，这样任何用到这个Mixin的类都能关联上这些方法。

2. 标注MyClass，让JSDoc识别它的继承关系 #

当你用Mixin创建MyClass后，要明确告诉JSDoc这个类同时继承了EventEmitter和Mixin的方法：

import SomeMixin from './SomeMixin';
import { EventEmitter } from 'events';

/**
 * 结合了EventEmitter和SomeMixin的类
 * @augments EventEmitter
 * @augments SomeMixinInterface
 */
class MyClass extends SomeMixin(EventEmitter) {}

const item = new MyClass();
// 现在JSDoc应该能识别item.func()和EventEmitter的所有方法了

@augments（和@extends功能类似）适合这种多重增强的场景，能让JSDoc把多个父类/接口的方法合并到当前类的文档里。

3. 修正函数参数的类型标注 #

之前你用@param {SomeMixin}是错的，因为SomeMixin是个工厂函数，不是类实例类型。应该用我们定义的SomeMixinInterface，或者直接用MyClass类型：

// 如果接受任何带有SomeMixin方法的实例：
/**
 * @param {SomeMixinInterface & EventEmitter} bar - 应用了SomeMixin的类实例
 */
function foo(bar) {
  bar.func(); // JSDoc会正确识别这个方法
  bar.emit('test'); // 也能识别EventEmitter的方法
}

// 如果明确只接受MyClass实例：
/**
 * @param {MyClass} bar
 */
function foo(bar) {}

const item = new MyClass();
foo(item); // 现在类型检查和文档都会正常工作

这样调整后，JSDoc就能正确识别SomeMixin的类属性、MyClass继承的所有方法，以及函数参数的类型啦。

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