How to document require-js AMD modules with jsdoc?

Question

After many days of frustrating experimenting with jsDoc, it seems that documenting of require-js modules (AMD) has its problems. To start with:

you can't tag your module as class:

define([
    "dcl/dcl",
], function (dcl) {
    /**
     * @class BaseClass
     * See {@tutorial getting-started}
     */
    var BaseClass = dcl(null,{
        foo:function(a){}
    });

    return BaseClass;
});

jsDoc will not output foo at all! Only by changing it to

/** @module BaseClass */
define([
    "dcl/dcl",
], function (dcl) {
    /**
     * @class module:BaseClass
     */
    var BaseClass = dcl(null,{
        foo:function(a){}
    });

    return BaseClass;
});

will enumerate foo as function in the docs. At least something but the trouble doesn't seem to end when it comes to modules. When looking at the jsdoc documentation (pretty poor), it treats Modules different; especially when it comes to constants and enums(link-able):

/** @module BaseClass */
define([
    "dcl/dcl",
], function (dcl) {
    /**
     * @class module:BaseClass
     */
    var BaseClass = dcl(null,{

        /**
         * 
         * @constant {String} module:BaseClass.COLLAPSED
         * @static
         * @member
         * @name module:BaseClass.COLLAPSED
         * */
        COLLAPSED : '__wcDockerCollapsedPanel',

        /**
         * Add a new docked panel to the docker instance.<br>
         * <b>Note:</b> It is best to use {@link wcDocker.COLLAPSED} after you have added your other docked panels, as it may ensure proper placement.
         * @param {module:BaseClass.COLLAPSED} [targetPanel]  - A target panel to dock relative to, or use {@link wcDocker.BaseClass} to collapse it to the side or bottom.
         * @returns {wcPanel|Boolean} - The newly created panel object, or false if no panel was created.
         */
        addPanel: function (targetPaneloptions) {}
    });

    return BaseClass;
});

Only by adding EVERYWHERE the module: prefix, your constants and enums become link-able. This looks pretty bad in the documentation. Also, I can't seem to define constants and enums in another module and link to them, memberOf doesn't help either.

So the question is: how to use jsDoc with AMD/Require-JS Modules, or how can I can make jsDoc treating AMD modules(created by var module =...) as classes?

ps: is it possible that its just buggy or not really working? Because I really tried all sorts of tags and combinations but no....Nothing really works as described in the docs.

Anyhow, any thought or links to examples are welcome. g

Mike Richards Mike Richards · Accepted Answer · 2016-09-22T18:37:12

I struggled with this same issue and finally came upon @lends

For you example I think all you have to change is

var BaseClass = dcl(null,{

to

var BaseClass = dcl(null, /** @lends BaseClass.prototype */{

Failure to include .prototype will result in jsdoc that defines the object literal members as static. I see you've explicitly defined COLLAPSED as static but not your method, so I'm unclear which you need or if dcl auto-detects constants and functions.

How to document require-js AMD modules with jsdoc?

1 Answers