我如何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的大块来将它弯曲到我的意愿.