如何在 JSDoc 中将参数指定为特定类的函数？

Question

我正在开发一个 JavaScript 类并使用 JSDoc 来获取文档。在构造函数中，我有一个参数

mutationAlgorithm

，它应该接受来自

Mutation

类的函数（例如，

Mutation.insert()

）。这是我当前的构造函数：

/**
 * @param {???} mutationAlgorithm - A function from the Mutation class.
 */
constructor(mutationAlgorithm = Mutation.insert) {
    this.mutationAlgorithm = mutationAlgorithm;
}

// Usage:
const obj = new Class(Mutation.insert);

我想在 JSDoc 中指定：

1. 这个参数是一个函数
2. 这个函数必须来自

   Mutation

   类

正确的 JSDoc 语法是什么？

Answer 1

您不能使用

@param {Mutation.insert}

或

@param {typeof Mutation.insert}

来强制参数具体为

Mutation.insert

。一种方法是为您的用例使用 callback 标签。

示例

/**
 * A mutation algorithm function.
 * @callback Mutation~insert
 * @param {string} foo - example param although u have none in your provided code
 * @returns {void}
 */
class Mutation {
    /**
     * Your insert function
     * @type {Mutation~insert}
     */
    static insert(foo) {
        // ...
    }
}

/**
 * @param {Mutation~insert} mutationAlgorithm - Your insert function from Mutation class
 */
constructor(mutationAlgorithm = Mutation.insert) {
    this.mutationAlgorithm = mutationAlgorithm;
}

说明

来自 JSDoc 文档：@callback 标签提供了有关可以传递给其他函数的回调函数的信息，包括回调的参数和返回值

将

@callback

视为定义函数的方式。输入什么（参数）和输出什么（返回类型）。定义回调后，您可以在任何需要指定参数应属于该类型函数的地方使用其名称。这样你就可以改变功能，只需要调整 JSDoc 的一处即可。