Javascript 如何记录嵌套对象'；什么方法？

我一直在尝试使用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出现在生成的文档中吗

---

另外，我曾在JSDoc网站上阅读过类似的页面，但它只描述了

foo.bar

，而不是

foo.bar.baz

，

您可以结合使用

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

bar4没有那张丑陋的属性表。ie@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;
});

参考资料-

---

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

这里有一个简单的方法：

/**
 * @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几个月了，用它来记录a和a。在某些方面，我更愿意听从jsdoc3的意愿，而不是必须键入大量的@-指令才能听从我的意愿。

您不能直接记录嵌套函数。我不喜欢Prongs解决方案，所以我使用了一个没有名称空间的不同实现（它是JS，而不是Java！）

更新：

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

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

/**@模块foobar*/
/**@函数*/
函数foobarbaz（）{
/* 
*您不能像您一样将函数中的属性作为成员进行文档化
*在Javascript中，函数是一级对象
*解决方法是使其成为其最近父级（模块）的@members。
*使用（请参阅：{@link…}）手动将其链接到函数，并给出
*它是一个@name。
*/
/**
*Foo对象（请参阅：{@link模块：foobar~foobarbaz}）
*@name foo
*@内部
*@私人
*@memberof模块：foobar
*@property{Object}foo-foo对象
*@property{Object}foo.bar-bar对象
*@property{function}foo.bar.baz-baz函数
*/
变量foo={
/* 
*您可以使用bar，或者如果
*@property description of foo.bar就够了，别管这个了。
*/
酒吧：{
/*
*与foo对象的限制一样，您只能记录成员
*这里我使用了与foo相同的技术，除了baz。
*/
/**
*Baz函数（请参阅：{@link模块：foobar~foo}）
*@函数
*@memberof模块：foobar
*@返回{string}一些字符串
*/
baz:function（）{/*…*/}
}
};
返回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的答案，我只有在使用注释代替了注释的情况下才能让它工作

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);
            },


            ...
        }
    }
}

---

谢谢，但那根本不起作用。最后，我看到了一个没有任何内容的foo文档页面（没有提及baz），以及一个没有baz方法的“全局”bar页面：-（事实上，如果我按字面意思使用你的代码，我甚至不明白：我只是得到一个没有任何内容的foo页面。但是如果我用我的实际代码做一些类似于你所建议的事情，我会得到一个没有任何内容的foo页面和一个没有任何内容的“全局”条形页面（即没有baz）。我从来不是说你必须按照我的例子来做。我只是说尝试使用它们。不管怎样。我做了。我放了两种方式的栏，都有不同的效果。我最后添加了四个栏。有很多方法可以记录内部对象。请尝试和评论。我可以解释更多具体的方法。你可以在上面的代码上运行jsdoc直接的。它起作用了…或者至少它起作用了很多！

@namespace foo.bar

似乎是我需要的缺失部分。唯一不太理想的是每个子级别（例如

bar

，

bar2

）获取自己的页面。理想情况下，我希望看到

bar

和

bar2

出现在

foo

的页面上（因为我正试图为foo模块生成一个文档页面，而不是为每个foo页面生成一堆页面）…是这样吗