我如何JSDoc嵌套對象的方法？

Question

我一直在嘗試使用JSDoc3來生成文件的文檔，但是我遇到了一些困難。 該文件（Require.js模塊）基本上如下所示：

define([], function() {

    /*
     * @exports mystuff/foo
     */
    var foo = {
        /**
         * @member
         */
        bar: {
            /**
             * @method
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

問題是，我無法讓baz出現在生成的文檔中。 相反，我只是得到一個foo/foo模塊的文檔文件，它列出了一個bar成員，但是bar沒有baz （只是foo源代碼的鏈接）。

我試圖改變bar的指令@property ，而是和我試圖改變baz的指令@member或@property ，但沒有什么幫助。 無論我做什么，巴茲似乎都不想表現出來。

有誰知道我可以用什么指令結構讓baz出現在生成的文檔中？

PS我試過在JSDoc網站http://usejsdoc.org/howto-commonjs-modules.html上閱讀這樣的頁面，但它只描述了foo.bar ，而不是foo.bar.baz 。

Answer 1

您可以將@module或@namespace與@memberof結合使用。

define([], function() {

    /**
     * A test module foo
     * @version 1.0
     * @exports mystuff/foo
     * @namespace foo
     */
    var foo = {
        /**
         * A method in first level, just for test
         * @memberof foo
         * @method testFirstLvl
         */
        testFirstLvl: function(msg) {},
        /**
         * Test child object with child namespace
         * @memberof foo
         * @type {object}
         * @namespace foo.bar
         */
        bar: {
            /**
             * A Test Inner method in child namespace
             * @memberof foo.bar
             * @method baz
             */
            baz: function() { /*...*/ }
        },
        /**
         * Test child object without namespace
         * @memberof foo
         * @type {object}
         * @property {method} baz2 A child method as property defination
         */
        bar2: {
            /**
             * A Test Inner method
             * @memberof foo.bar2
             * @method baz2
             */
            baz2: function() { /*...*/ }
        },
        /**
         * Test child object with namespace and property def.
         * @memberof foo
         * @type {object}
         * @namespace foo.bar3
         * @property {method} baz3 A child method as property defination
         */
        bar3: {
            /**
             * A Test Inner method in child namespace
             * @memberof foo.bar3
             * @method baz3
             */
            baz3: function() { /*...*/ }
        },
        /**
         * Test child object
         * @memberof foo
         * @type {object}
         * @property {method} baz4 A child method
         */
        bar4: {
             /**
             * The @alias and @memberof! tags force JSDoc to document the
             * property as `bar4.baz4` (rather than `baz4`) and to be a member of
             * `Data#`. You can link to the property as {@link foo#bar4.baz4}.
             * @alias bar4.baz4
             * @memberof! foo#
             * @method bar4.baz4
             */
            baz4: function() { /*...*/ }
        }
    };

    return foo;
});

根據評論編輯:(模塊的單頁解決方案）

bar4沒有那個丑陋的屬性表。 即@property從bar4中刪除。

define([], function() {

    /**
     * A test module foo
     * @version 1.0
     * @exports mystuff/foo
     * @namespace foo
     */
    var foo = {
        /**
         * A method in first level, just for test
         * @memberof foo
         * @method testFirstLvl
         */
        testFirstLvl: function(msg) {},
        /**
         * Test child object
         * @memberof foo
         * @type {object}
         */
        bar4: {
             /**
             * The @alias and @memberof! tags force JSDoc to document the
             * property as `bar4.baz4` (rather than `baz4`) and to be a member of
             * `Data#`. You can link to the property as {@link foo#bar4.baz4}.
             * @alias bar4.baz4
             * @memberof! foo#
             * @method bar4.baz4
             */
            baz4: function() { /*...*/ },
            /**
             * @memberof! for a memeber
             * @alias bar4.test
             * @memberof! foo#
             * @member bar4.test
             */
             test : true
        }
    };

    return foo;
});

參考 -

1. 關於嵌套命名空間的另一個問題
2. 有關使用命名空間的替代方法
3. 記錄文字對象

*注意我自己沒試過。 請嘗試分享結果。

Answer 2

這是一個簡單的方法：

/**
 * @module mystuff/foo
 * @version 1.0
 */
define([], function() {

/** @lends module:mystuff/foo */
var foo = {
    /**
     * A method in first level, just for test
     */
    testFirstLvl: function(msg) {},
    /**
     * @namespace
     */
    bar4: {
        /**
         * This is the description for baz4.
         */
        baz4: function() { /*...*/ },
        /**
         * This is the description for test.
         */
        test : true
    }
};

return foo;
});

請注意，jsdoc可以推斷類型baz4.baz4並test而不必說@method和@member。

至於讓jsdoc3將類和命名空間的文檔放在與定義它們的模塊相同的頁面上，我不知道該怎么做。

幾個月來我一直在使用jsdoc3，用它來記錄一個小型庫和一個大型應用程序 。 我更傾向於在某些方面彎曲到jsdoc3的意志，而不是輸入@ -directives的大塊來屈服於我的意志。

Answer 3

您無法直接記錄嵌套函數。 我不喜歡Prongs解決方案，所以我使用了不帶命名空間的不同實現（它是JS， 而不是 Java！）。

更新：

我更新了我的答案，以反映OP給出的確切用例（這是公平的，因為使用JSdoc非常痛苦）。 以下是它的工作原理：

/** @module foobar */

/** @function */
function foobarbaz() {
    /* 
     * You can't document properties inside a function as members, like you
     * can for classes. In Javascript, functions are first-class objects. The
     * workaround is to make it a @memberof it's closest parent (the module).
     * manually linking it to the function using (see: {@link ...}), and giving
     * it a @name.
     */

    /**
     * Foo object (see: {@link module:foobar~foobarbaz})
     * @name foo
     * @inner
     * @private
     * @memberof module:foobar
     * @property {Object} foo - The foo object
     * @property {Object} foo.bar - The bar object
     * @property {function} foo.bar.baz - The baz function
     */
    var foo = {

        /* 
         * You can follow the same steps that was done for foo, with bar. Or if the
         * @property description of foo.bar is enough, leave this alone. 
         */
        bar: {

            /*
             * Like the limitation with the foo object, you can only document members 
             * of @classes. Here I used the same technique as foo, except with baz.
             */

            /**
             * Baz function (see: {@link module:foobar~foo})
             * @function
             * @memberof module:foobar
             * @returns {string} Some string
             */
            baz: function() { /*...*/ }
        }
    };

    return foo;
}

不幸的是，JSdoc是Java的一個端口，所以它有很多對Java有意義的功能，但不適用於JS，反之亦然。 例如，由於JS函數是第一類對象，因此可以將它們視為對象或函數。 所以做這樣的事情應該有效：

/** @function */
function hello() {
  /** @member {Object} */
  var hi = {};
}

但事實並非如此，因為JSdoc將其視為一種功能。 你必須使用命名空間，我的@link技術，或者使它成為一個類：

/** @class */
function Hello() {
  /** @member {Object} */
  var hi = {};
}

但那也沒有意義。 JS中是否存在類？ 不 ，他們沒有。

我認為我們真的需要找到更好的文檔解決方案。 我甚至在文檔中看到了應該如何顯示類型的不一致（例如{object} vs {Object} ）。

您還可以使用我的技術來記錄閉包 。

Answer 4

為了改進Prongs對JSDoc3的回答，當我使用@instance注釋代替@member時，我才能使它工作。

ES6示例代碼如下：

class Test
{
    /**
     * @param {object} something
     */
    constructor(something)
    {
        this.somethingElse = something;

        /**
         * This sub-object contains all sub-class functionality.
         *
         * @type {object}
         */
        this.topology = {
            /**
             * Informative comment here!
             *
             * @alias topology.toJSON
             * @memberof! Test#
             * @instance topology.toJSON
             * 
             * @returns {object} JSON object
             */
            toJSON()
            {
                return deepclone(privatesMap.get(this).innerJSON);
            },


            ...
        }
    }
}