javascript - JSDoc 记录原型(prototype)继承

Question

假设我们正在构建一个嵌套的命名空间，我们将在其中根据需要对多个对象进行原型(prototype)设计。默认情况下，对象 window.blah.foo 是空的。然后，我们在一个原型(prototype)中对所有子对象及其功能进行原型(prototype)设计。当如下记录时，我们将所有内部函数显示为全局函数。现在假设您有数十个以相同方式构建的文件。我们如何记录这一点，以便 .bar1()、bar2() 和 bar3() 函数成为 window.blah.foo 对象的方法，特别是当它的实例化发生在该文件外部时，可能会多次。

/**
 * Blah - Our very own global Namespace
 * @namespace
 * @type {object}
 * @global
 * @public
*/
window.blah = window.blah || {};

/**
 * Immediately-Invoked Function Expression (IIFE). 
 * @function
 * @param {object} w - Global window object.
 * @returns {Object} window.blah.foo
*/
(function (w) {

    // strict JS
    'use strict';

    /**
     * Create instance of w.blah.foo constructor
     * @constructor
    */
    w.blah.foo = function () {

   };

    /**
     * Append properties and methods to an instance of window.blah.foo
     * @constructor
    */
    w.blah.foo.prototype = {

        /**
         * Dummy function to return the number 1.
         * @method bar1
        */
        bar1: function () {
            console.log(1);
        },

        /**
         * Dummy function to return the number 2.
         * @method bar2
        */
        bar2: function () {
            console.log(2);
        },

        /**
         * Dummy function to return the number 3.
         * @method bar3
        */
        bar3: function () {
            console.log(3);
        }

    };

}(window));

Answer 1

以下代码会将 barX 方法移动到它们所属的位置。请注意，jsdoc 与记录 IIFE 的 doclet 没有任何关系。将方法放在正确位置的关键是 /** @lends blah.foo# */。请参阅 @lends 的文档。 # 告诉 jsdoc 借给 blah.foo 的项目属于该类的实例。请参阅 namepaths 上的文档了解更多详情。

/**
 * Blah - Our very own global Namespace
 * @namespace
 * @global
 */
window.blah = window.blah || {};

/**
 * Immediately-Invoked Function Expression (IIFE).
 * @function
 * @param {object} w - Global window object.
 * @returns {Object} window.blah.foo
 */
(function (w) {
    // strict JS
    'use strict';

    /**
     * Create instance of w.blah.foo constructor
     * @constructor
     * @name blah.foo
     */
    w.blah.foo = function () {

    };

    /** @lends blah.foo# */
    w.blah.foo.prototype = {

        /**
         * Dummy function to return the number 1.
         */
        bar1: function () {
            console.log(1);
        },

        /**
         * Dummy function to return the number 2.
         */
        bar2: function () {
            console.log(2);
        },

        /**
         * Dummy function to return the number 3.
         */
        bar3: function () {
            console.log(3);
        }

    };

}(window));