JSDoc3: How to document a AMD module that returns a function

Question

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?

score 2 · Answer 1 · answered May 28 '14 at 12:20

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.

how if i have to return object with different functions Example : return {x:fn1,y:fn2}; — jsduniya, Oct 25 '18 at 14:42

score 1 · Accepted Answer · answered Jun 02 '14 at 15:23

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.

Note that the name `exports` is special: any other name **will not** show up in the documentation. — Sharadh, Dec 04 '15 at 03:20

JSDoc3: How to document a AMD module that returns a function

2 Answers2