我一直在尝试使用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出现在生成的文档中？
P.S。我尝试在JSDoc网站http://usejsdoc.org/howto-commonjs-modules.html上阅读这样的网页，但它只描述了foo.bar而不是foo.bar.baz的情况。
答案 0 :(得分：48)
您可以将@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 :(得分：7)
这是一个简单的方法：
/**
* @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，用它来记录small library和large application。我更倾向于在某些方面屈服于jsdoc3的意志，而不是输入@ -directives的大块来屈服于我的意志。
答案 2 :(得分：0)
您无法直接记录嵌套函数。我不喜欢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}）。
您还可以使用我的技术来记录closures。
答案 3 :(得分：0)
为了改善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);
},
...
}
}
}