如何 JSDoc 嵌套对象的方法

您可以将@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. 记录文本对象

*注意我自己没有尝试过。请尝试分享结果。

这里有一个简单的方法：

/**
 * @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 的意愿，而不是必须键入大量 @-指令来屈服于我的意愿。

不能直接记录嵌套函数。我不喜欢 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} (。

你也可以使用我的技术来记录闭包。

只是为了稍微改进 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);
            },

            ...
        }
    }
}