javascript - 使用 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