JSDoc3：如何记录返回函数的 AMD 模块答案

【问题标题】：JSDoc3: How to document a AMD module that returns a functionJSDoc3：如何记录返回函数的 AMD 模块
【发布时间】：2014-07-12 13:29:15
【问题描述】：

我正在尝试寻找一种使用 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 中列出的模式都不适合我。

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

【问题讨论】：

标签： javascript requirejs amd jsdoc jsdoc3

【解决方案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 的额外内部函数。

【讨论】：

如果我必须返回具有不同功能的对象示例：return {x:fn1,y:fn2};

【解决方案2】：

以下似乎产生了一个看起来完全可以接受的结果：

/**
 * 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 模块来说并不完美，但我认为文档的读者能够理解模块导出的内容。

【讨论】：

请注意，名称 exports 是特殊的：任何其他名称不会出现在文档中。