使用JSDoc記錄工廠

Question

為了避免在我的JavaScript代碼中使用new ，我編寫工廠來創建對象。

我嘗試了很多組合，給我最滿意的結果如下：

/**
 * Document module
 * @module app/document
 */
(function () {
    'use strict';

    /**
     * Factory that creates a document object.
     * @alias module:app/document.factory
     * @return {document}
     */
    function document() {
        /**
         * Get document id
         * @method id
         * @return {String}
         */
        var id = function id() {...},
            api = {
                id: id
            };

        return api;
    }

    /**
     * This module exports the {@link module:app/document.factory|factory} function.
     */
    module.exports = document;
}());

這些注釋的問題是沒有定義document對象。 因此，我無法在另一個對象中引用此對象，並且在擴展此對象時無法繼承其文檔。

記錄此類對象的適當方法是什么？

如果我使用@typedef標記，我會獲得正確記錄的靜態factory方法和document對象，但JSDoc不會生成id方法文檔：

/**
 * Document module.
 * @module app/document
 */
(function () {
    'use strict';

    /**
     * Factory that creates a document object.
     * @function module:app/document.factory
     * @return {document}
     */
    function factory(agent) {
        /**
         * @callback document~id
         * @returns {String}
         */
        var id = function id() {...},

            /**
             * @typedef document
             * @property {document~id} id
             */
            document = {
                id: id
            };

        return document;
    }

    module.exports = factory;
}());

Answer 1

我的建議是使用@typedef定義類型，然后用@type {FactoryDe​​finition}注釋module.exports = factory來很好地定義模塊的導出。

 /** @typedef {{ id: !string }} */
 var DocumentDefinition;

 /** @typedef {!function(!object):!DocumentDefinition} */
 var FactoryDefinition;

/** @type {FactoryDefinition} */
module.exports = factory

Answer 2

我總是在我的模塊包裝器外部使用@typedef在那里我總結了模塊公開的完整功能集。 這是我在WebStorm IDE中設法完成代碼並生成有用的HTML文檔的唯一方法。

/** @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
 */

(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) {
            const
                push = function(queue, item) {
                    const
                        clonedQueue = queue.slice();
                    clonedQueue.push(item);

                    return clonedQueue.sort(comparator);
                },
                // ...
            return {
                push: push,
                pop: pop
            };
        }

        return priorityQueueFactory;
}));

生成的文檔看起來像這樣 。