JSDoc3: How to document a AMD module that returns a function
I'm trying to find a way to document AMD modules using JSDoc3.
/**
* 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.
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. 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 .
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.
链接地址: http://www.djcxy.com/p/70422.html上一篇: 带有Dojo和AMD的JSDoc3