Search code examples
javascriptrequirejsamdjsdocjsdoc3

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?


Solution

  • 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.