如何将 jsdoc 与工厂函数一起使用？答案

【问题标题】：How do I use jsdoc with factory functions?如何将 jsdoc 与工厂函数一起使用？
【发布时间】：2019-02-08 05:08:29
【问题描述】：

所以我有一个导出工厂函数的模块。工厂函数接受设置并返回绑定在该设置对象上的库。我一辈子都想不出如何用 jsdocs 来记录它；我一直在玩命名空间、typedef 和memberof，直到我头晕目眩。无论我做什么，它只是没有将函数列为库定义的一部分。帮忙？

如果我完全删除 memberof，我可以让它们显示为全局函数，但到目前为止我没有尝试过让它们显示为成员函数

示例代码：

/**
 * @namespace ServerControl
 */
/**
 * @typedef {Object} Library
 */

/**
 * Factory function that constructs a lib
 * @param {*} settings Settings for constructing a lib
 * @param {*} rancher The rancher library to be used by the lib
 * @returns {ServerControl~Library} The lib
 */
module.exports = function(settings, rancher) {
    return {
        /**
         * Evacuate a host
         * @memberof {...ServerControl~Library}
         * @method evacuate
         * @param {String} name The name of the host to evacuate
         * @returns {Promise} A promise that fulfills when the evacuation is done
         */
        evacuate: name => {
            const server = settings.servers.filter(item => item.display === name)[0];
            return rancher.evacuateHost(server.host, server.env);
        }
        // [more methods snipped]
    }

【问题讨论】：

标签： jsdoc jsdoc3

【解决方案1】：

我有同样的问题，我的模块总是暴露工厂函数或函数映射。我总是在模块包装器之外使用@typedef。这样我就可以在 IDEA 中完成代码并且可以生成漂亮的 HTML 文档。

Here the generated documentation 这个例子：

/** @namespace SharedLib */

/**
 * @typedef SharedLib.PriorityQueueFactory
 * @function
 * @template T
 * @param {function(T, T): Boolean} comparator Comparison function like for <code>Array.prototype.sort</code>
 * @return {{pop: function(Array<T>): Array<Array<T>| T>, push: function(Array<T>, T): Array<T>}} an object containing the functions to manage the queue
 */

// UMD wrapper - sorry!
(function (root, factory) {
    if (typeof define === 'function' && define.amd) {
        define([], factory);
    }
    else if (typeof module === 'object' && module.exports) {
        module.exports = factory();
    }
    else {
        root.returnExports = factory();
    }
}(typeof self !== 'undefined' ? self : this,
    function () {

        /** @type {SharedLib.PriorityQueueFactory} */
        function priorityQueueFactory(comparator) {
            // ...
    return priorityQueueFactory;
}));

【讨论】：