[英]JSDoc3: How to document a AMD module that returns a function
I'm trying to find a way to document AMD modules using JSDoc3. 我正试图找到一种使用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
};
});
Sadly none of the patterns listed on http://usejsdoc.org/howto-commonjs-modules.html work for me. 可悲的是, http://usejsdoc.org/howto-commonjs-modules.html上列出的模式都不适用于我。
How can I generate a proper documentation that lists the parameters and return value of the function exported by the module? 如何生成一个适当的文档,列出模块导出的函数的参数和返回值?
As of the latest stable version (3.2.2) I do not think there is a way to do use jsdoc to produce documentation that will show that the module itself accepts parameters and returns some value. 从最新的稳定版本(3.2.2)开始,我认为没有办法使用jsdoc生成文档,这些文档将显示模块本身接受参数并返回一些值。 The closest I can come to the ideal is this:
我最接近理想的是:
/**
* 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
};
});
The generated documentation for the module will have an extra inner function named self
. 生成的模块文档将具有一个名为
self
的额外内部函数。
The following seems to generate a result which looks quite acceptable: 以下似乎生成了一个看起来完全可以接受的结果:
/**
* 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;
});
Which describes the module and the function with something like: 其中描述了模块和功能,例如:
require("path/to/module")(foo, bar)
That's not perfect for AMD modules but I think the reader of the documentation is able to understand what the module exports. 这对于AMD模块来说并不完美,但我认为文档的读者能够理解模块输出的内容。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.