如何使用 jsdoc 记录 require-js AMD 模块？答案

【问题标题】：How to document require-js AMD modules with jsdoc?如何使用 jsdoc 记录 require-js AMD 模块？
【发布时间】：2015-11-27 06:39:14
【问题描述】：

在对 jsDoc 进行了许多令人沮丧的试验之后，似乎记录 require-js 模块 (AMD) 有其问题。开始：

你不能将你的模块标记为类：

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

    return BaseClass;
});

jsDoc 根本不会输出 foo！只需将其更改为

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

    return BaseClass;
});

将枚举 foo 作为文档中的函数。至少有些东西，但在模块方面，麻烦似乎并没有结束。在查看 jsdoc 文档时（很差），它对待 Modules 是不同的；尤其是在常量和枚举（可链接）方面：

/** @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;
});

只有在每个地方添加 module: 前缀，你的常量和枚举才能链接。这在文档中看起来很糟糕。另外，我似乎无法在另一个模块中定义常量和枚举并链接到它们，memberOf 也无济于事。

所以问题是：如何将 jsDoc 与 AMD/Require-JS 模块一起使用，或者如何使 jsDoc 将 AMD 模块（由 var module =... 创建）视为类？

ps：有没有可能它只是有问题或没有真正工作？因为我真的尝试了各种标签和组合，但没有......没有像文档中描述的那样真正起作用。

无论如何，欢迎任何想法或示例链接。 g

【问题讨论】：

标签： jsdoc

【解决方案1】：

我在同样的问题上苦苦挣扎，最后遇到了@lends

以你为例，我认为你所要做的就是改变

var BaseClass = dcl(null,{

到

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

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

【讨论】：