使用 JSDOC 记录范围答案

【问题标题】：document scopes with JSDOC使用 JSDOC 记录范围
【发布时间】：2014-04-14 20:22:40
【问题描述】：

我很难用 JSDOC 记录范围，任何人都可以知道记录以下代码的正确方法是什么：

（现在jsdoc生成GLOBAL函数中的所有方法，应该属于WorkAreaPlugin）

/**
 * @namespaces Retalix.StoreOfficeClient.Web.Scripts.General.WorkArea
 * @scope WorkAreaPlugin
 */
(function ($, undefined) {

/**
 * Description
 * @constructor
 * @method ctor
 * @param {} options     
 * @return 
 */
var ctor = function (options) {
    var self = this;
    var _data;
    var _new;
    var _grids = {};

    if (this.setupAjaxCrud) {
        this.setupAjaxCrud();
    }

    $.extend(self,
        {
        /**
         * Sets the data property of the current scope and setups the set_isDirty and the get_isDirty functions if not exist to the data object 
         * @method set_data
         * @param {} data
         * @param {} triggerChange
         * @return 
         */
        set_data: function (data, triggerChange) {
            _data = data || {};
            if (!_data.set_isDirty) {
                $.setupDirtyFunctions(_data);
            }
            if (triggerChange !== false) {
                self.trigger("dataChanged", [_data, self]);
            }
        }
    });

    this.bind("login", function () {
        var isDirty = self.isDirty();
        if (!isDirty && self.loader && $.isFunction(self.loader.doLoading)) {
            self.reload();
        }
    });
};

StoreOfficeClient.Plugins.Register("workArea", undefined, undefined, ctor);

})(jQuery);

【问题讨论】：

你用的是什么版本的jsdoc？我不记得曾经看到过为 3.x 系列记录的@scope。（但文档有时是有缺陷的。）
我m using jsdoc3.3.0 , I在这里看到了@scope 选项：code.google.com/p/jsdoc-toolkit/wiki/DocExamples#Changing_Scope 但它对我不起作用。你将如何记录这个？（即使没有@scope）
您看到的文档适用于 jsdoc 2.x。
好的，那么如何推荐呢？
糟糕。之前忘记提这个了。不要使用 jsdoc 3.3.0，因为它仍然是 alpha 和 bug，请使用 3.2.x 系列中的最新版本。（我想你已经看到我已经提交了一个答案。）

标签： javascript jquery jsdoc

【解决方案1】：

首先让我指出，使用 jsdoc 记录 JavaScript 代码通常归结为一个约定问题，以及您希望如何向阅读文档的人呈现 JS 实体之间的关系。所以以下是一个可能的答案。

以下内容会将所有内容放在一个命名空间中：

/**
 * @namespace Retalix.StoreOfficeClient.Web.Scripts.General.WorkArea.WorkAreaPlugin
 *
 */
(/** @lends Retalix.StoreOfficeClient.Web.Scripts.General.WorkArea.WorkAreaPlugin */ function ($, undefined) {

/**
 * Description
 * @constructor
 * @param {} options
 */
var ctor = function (options) {
    var self = this;
    var _data;
    var _new;
    var _grids = {};

    if (this.setupAjaxCrud) {
        this.setupAjaxCrud();
    }

    $.extend(self,
             /** @lends Retalix.StoreOfficeClient.Web.Scripts.General.WorkArea.WorkAreaPlugin~ctor# */ {
        /**
         * Sets the data property of the current scope and setups the set_isDirty and the get_isDirty functions if not exist to the data object
         * @param {} data
         * @param {} triggerChange
         */
        set_data: function (data, triggerChange) {
            _data = data || {};
            if (!_data.set_isDirty) {
                $.setupDirtyFunctions(_data);
            }
            if (triggerChange !== false) {
                self.trigger("dataChanged", [_data, self]);
            }
        }
    });

    this.bind("login", function () {
        var isDirty = self.isDirty();
        if (!isDirty && self.loader && $.isFunction(self.loader.doLoading)) {
            self.reload();
        }
    });
};

StoreOfficeClient.Plugins.Register("workArea", undefined, undefined, ctor);

})(jQuery);

【讨论】：

jsdoc 输出它就像 ctor 是一个类（在 Classes 下有 ctor），而 ctor 只是构造函数。另外，我不希望它被称为类，有没有机会告诉 jsdoc WorkAreaPlugin 是上述名称空间中的插件？
jsdoc 在“构造函数”和“类”的概念之间没有区别。请参阅@constructor 上的文档：它的同义词是@class。并且 jsdoc 没有“插件”的概念。您可以使 ctor 和 set_data 成为与您的插件相对应的命名空间的常规函数。