javascript - JSDoc3:如何记录返回函数的 AMD 模块

Question

我正在尝试找到一种使用 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 上没有列出任何模式为我工作。

如何生成列出模块导出函数的参数和返回值的适当文档？

Answer 1

从最新的稳定版本 (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 的额外内部函数。