JSDoc：指定作为参数传递的对象的类型？

Question

我在模块中有一个方法。它采用的对象是非常特定的类的实例。例如：

    /** Validate a unit against the database's list of valid units
     * @param {Object} db - ???
     * @param {string} unit - unit to validate
     * @returns {Promise} Promise to query unit validation
     */
    validateUnit: (db, unit) => {
        return new Promise((resolve, reject) => {

我想非常清楚地表明db参数是从require('knex')({...})返回的Knex对象。

Answer 1

我认为总的来说，我可能会使用typedef：

/**
 * @typedef {Function} Knex
 */

请注意，Knex exports a function不是普通的JavaScript对象。它确实为该函数添加了属性，并且正如我们在JS中所知，函数也是对象！但是，如果我们采用这种方式，我认为您的IDE可能会显示：

validateUnit(db: Function, unit: string)

我收集到的

并不是您所追求的。如果我们这样做：

/**
 * @typedef {Object} Knex
 * @property {Function} select - Select columns to retrieve
 * @see {@link https://knexjs.org|Documentation}
 */

我们得到：

您可以根据需要使用尽可能多的细节，或者保持简单。有人可能已经为您详尽地使用了JSDoc'd Knex，但我还没有搜索！然后，您就有了一种可以用于参数的类型：

/** Validate a unit against the database's list of valid units
 * @param {Knex} db - database instance
 * @param {string} unit - unit to validate
 * @returns {Promise} Promise to query unit validation
 */