我正试图找到一种使用JSDoc3记录AMD模块的方法。
/**
* Module description.
*
* @module path/to/module
*/
define(['jquery', 'underscore'], function (jQuery, _) {
/**
* @param {string} foo Foo-Description
* @param {object} bar Bar-Description
*/
return function (foo, bar) {
// insert code here
};
});
遗憾的是,http://usejsdoc.org/howto-commonjs-modules.html上列出的所有模式都不适合我。
如何生成一个适当的文档,列出模块导出的函数的参数和返回值?
答案 0 :(得分:2)
从最新的稳定版本(3.2.2)开始,我认为没有办法使用jsdoc生成文档,这些文档将显示模块本身接受参数并返回一些值。我最接近理想的是:
/**
* Module description.
*
* @module path/to/module
*/
define(['jquery', 'underscore'], /** @lends module:path/to/module */
function (jQuery, _) {
/**
* The following function documents the parameters that the module
* takes and its return value. Do not call as
* <code>module.self(...)</code> but as <code>module()</code>.
*
* @param {string} foo Foo-Description
* @param {object} bar Bar-Description
*/
return function self(foo, bar) {
// insert code here
};
});
生成的模块文档将包含一个名为self
的额外内部函数。
答案 1 :(得分:1)
以下似乎产生了一个看起来完全可以接受的结果:
/**
* Module description
*
* @module path/to/module
*/
define(['jquery', 'underscore'], function (jQuery, _) {
/**
* Description for function.
*
* @param {string} foo Foo-Description
* @param {object} bar Bar-Description
*/
var exports = function () {
// insert code here
};
return exports;
});
其中描述了模块和功能,如:
require("path/to/module")(foo, bar)
这对于AMD模块来说并不完美,但我认为文档的读者能够理解模块导出的内容。