我如何JSDoc嵌套对象的方法？ [英] How do I JSDoc A Nested Object's Methods?

问题描述

我一直在尝试使用JSDoc3来生成文件的文档，但是我遇到了一些困难。该文件（Require.js模块）基本上如下所示：

I've been trying to use JSDoc3 to generate documentation on a file, but I'm having some difficulty. The file (which is a Require.js module) basically looks like this:

define([], function() {

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

    return foo;
}

问题是，我无法在生成的文档中显示 baz 。相反，我只是获得的文档文件foo / foo 模块，列出 bar 成员，但 bar 没有 baz （只是指向 foo 的源代码的链接）。

The problem is, I can't get baz to show up in the generated documentation. Instead I just get a documentation file for a foo/foo module, which lists a bar member, but bar has no baz (just a link to foo's source code).

我已经尝试将 bar 的指令更改为 @property ，我尝试更改 baz 对 @member 或 @property ，但这些都没有帮助。无论我做什么，baz似乎都不想出现。

I've tried changing bar's directive to @property instead, and I've tried changing baz's directive to @member or @property, but none of that helps. No matter what I do, baz just doesn't seem to want to show up.

有谁知道我可以用什么指令结构让baz出现在生成的文件？

Does anyone know what directive structure I could use to get baz to appear in the generated documentation?

PS我已经尝试在JSDoc网站上阅读这样的页面 http://usejsdoc.org/howto-commonjs-modules.html ，但它只描述了 foo.bar 的情况，而不是 foo.bar.baz 。

P.S. I've tried reading pages like this one on the JSDoc site http://usejsdoc.org/howto-commonjs-modules.html, but it only describes cases of foo.bar, not foo.bar.baz.

推荐答案

您可以结合使用 @ module 或 @namespace 以及 @ memberof 。

You can use a combination of @module or @namespace along with @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;
});

根据评论编辑：（模块的单页解决方案）

EDIT as per Comment: (Single page solution for module)

bar4没有那个丑陋的属性表。即@property从bar4中移除。

bar4 without that ugly property table. ie @property removed from 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. 记录文字对象

1. Another Question about nested namespaces
2. For alternative way of using Namespaces
3. Documenting literal objects

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

*Note I haven't tried it myself. Please try and share the results.

这篇关于我如何JSDoc嵌套对象的方法？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！