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

Answer 1

我在同样的问题上挣扎，终于遇到了@lends

对于你的例子，我认为你需要改变的是

var BaseClass = dcl(null,{

到

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

未包括.prototype将导致jsdoc将对象文字成员定义为 static 。我看到你明确将COLLAPSED定义为静态但不是你的方法，所以我不清楚你需要什么，或者dcl是否自动检测常量和函数。

How to document require-js AMD modules with jsdoc?

1 个答案: