From 9905cfa01bedddf63c7d058cb77d93e2f5da4de8 Mon Sep 17 00:00:00 2001 From: Yuri Kuznetsov Date: Sat, 11 Jun 2022 12:22:53 +0300 Subject: [PATCH] jsdocs --- client/src/collection.js | 78 +++++++++++++++++++++++++++++++++------- client/src/controller.js | 22 ++++++------ client/src/model.js | 65 ++++++++++++++++++++++++++++----- client/src/router.js | 22 ++++++++---- client/src/view.js | 44 ++++++++++++++++------- 5 files changed, 182 insertions(+), 49 deletions(-) diff --git a/client/src/collection.js b/client/src/collection.js index 570cf201a6..abf383db1e 100644 --- a/client/src/collection.js +++ b/client/src/collection.js @@ -28,6 +28,23 @@ define('collection', [], function () { + /** + * On sync with backend. + * + * @event Espo.Collection#sync + * @param {Espo.Collection} collection A collection. + * @param {Object} response Response from backend. + * @param {Object} o Options. + */ + + /** + * Any number of models have been added, removed or changed. + * + * @event Espo.Collection#update + * @param {Espo.Collection} collection A collection. + * @param {Object} o Options. + */ + /** * Add a model or models. Firing an `add` event for each model, and an `update` event afterwards. * @@ -68,69 +85,98 @@ define('collection', [], function () { * @class Espo.Collection * @extends Backbone.Collection.prototype * @mixes Backbone.Events - * - * @property {number} length - A number of records. - * @property {Espo.Model[]} models - Models. */ var Collection = Backbone.Collection.extend(/** @lends Espo.Collection.prototype */ { /** * An entity type. - * @property {string} + * + * @name entityType + * @type {string} + */ + + /** + * A number of records. + * + * @name length + * @type {number} + */ + + /** + * Models. + * + * @name length + * @type {Espo.Model[]} + */ + + /** + * A name. + * + * @type {string} */ name: null, /** * A total number of records. - * @property {number} + * + * @type {number} */ total: 0, /** * A current offset (for pagination). - * @property {number} + * + * @type {number} */ offset: 0, /** * A max size (for pagination). - * @property {number} + * + * @type {number} */ maxSize: 20, /** * True for desc order. - * @property {?boolean} + * + * @type {?boolean} */ order: null, /** * An order-by field. - * @property {?string} + * + * @type {?string} */ orderBy: null, /** * A where clause. - * @property {?Array.{Object}} + * + * @type {?Array.} */ where: null, whereAdditional: null, /** - * @property {number} + * @type {number} */ lengthCorrection: 0, /** - * @property {number} + * @type {number} */ maxMaxSize: 0, + /** + * @private + */ _user: null, /** + * @protected * @param {Espo.Model[]} models * @param {Object} options */ @@ -150,6 +196,9 @@ define('collection', [], function () { this.data = {}; }, + /** + * @private + */ _onModelEvent: function(event, model, collection, options) { if (event === 'sync' && collection !== this) { return; @@ -159,6 +208,8 @@ define('collection', [], function () { }, /** + * Reset. + * * @param {Espo.Model[]} models * @param {Object} options */ @@ -336,6 +387,9 @@ define('collection', [], function () { return where; }, + /** + * @protected + */ getUser: function () { return this._user; }, diff --git a/client/src/controller.js b/client/src/controller.js index 72d66f4896..82eed5bf6e 100644 --- a/client/src/controller.js +++ b/client/src/controller.js @@ -29,7 +29,7 @@ define('controller', [], function () { /** - * @callback Espo.Controller.viewCallback + * @callback Espo.Controller~viewCallback * @param {Espo.View} view A view. */ @@ -75,35 +75,37 @@ define('controller', [], function () { /** * A default action. * - * @param {string} + * @type {string} */ defaultAction: 'index', /** * A name. * - * @param {(string|false)} + * @type {(string|false)} */ name: false, /** * Params. * - * @param {Object} + * @type {Object} + * @private */ params: null, /** * A view factory. * - * @param {Bull.ViewFactory} + * @type {Bull.ViewFactory} + * @protected */ viewFactory: null, /** * A model factory. * - * @param {Espo.ModelFactory} + * @type {Espo.ModelFactory} * @protected */ modelFactory: null, @@ -111,7 +113,7 @@ define('controller', [], function () { /** * A controller factory. * - * @param {Espo.ControllerFactory} + * @type {Espo.ControllerFactory} * @protected */ controllerFactory: null, @@ -400,7 +402,7 @@ define('controller', [], function () { /** * Create a master view, render if not already rendered. * - * @param {Espo.Controller.viewCallback} callback A callback with a created master view. + * @param {Espo.Controller~viewCallback} callback A callback with a created master view. */ master: function (callback) { let entire = this.get('entire'); @@ -442,7 +444,7 @@ define('controller', [], function () { * Create a main view in the master. * @param {String} view A view name. * @param {Object} options Options for view. - * @param {Espo.Controller.viewCallback} [callback] A callback with a created view. + * @param {Espo.Controller~viewCallback} [callback] A callback with a created view. * @param {boolean} [useStored] Use a stored view if available. * @param {boolean} [storedKey] A stored view key. */ @@ -582,7 +584,7 @@ define('controller', [], function () { * * @param {String} view A view name. * @param {Object} options Options for a view. - * @param {Espo.Controller.viewCallback} [callback] A callback with a created view. + * @param {Espo.Controller~viewCallback} [callback] A callback with a created view. */ entire: function (view, options, callback) { let master = this.get('master'); diff --git a/client/src/model.js b/client/src/model.js index c2083a61b2..e82279f664 100644 --- a/client/src/model.js +++ b/client/src/model.js @@ -58,26 +58,75 @@ define('model', [], function () { * @param {Object} [options] Options. */ + /** + * When attributes have changed. + * + * @event Espo.Model#change + * @param {Espo.Model} model A model. + * @param {Object} o Options. + */ + + /** + * On sync with backend. + * + * @event Espo.Model#sync + * @param {Espo.Model} model A model. + * @param {Object} response Response from backend. + * @param {Object} o Options. + */ + /** * @class Espo.Model * @extends Backbone.Model * @mixes Backbone.Events - * - * @property {?string} id - An ID. - * @property {Object} attributes - Attribute values. - * @property {string} cid - An ID unique among all models. */ let Model = Dep.extend(/** @lends Espo.Model.prototype */{ + /** + * An entity type. + * + * @name entityType + * @property {string} + * @public + */ + + /** + * A record ID. + * + * @name cid + * @type {?string} + * @public + */ + + /** + * An ID, unique among all models. + * + * @name cid + * @type {string} + * @public + */ + + /** + * Attribute values. + * + * @name attributes + * @type {Object} + * @public + */ + /** * A root URL. - * @property {?string} + * + * @type {?string} + * @public */ urlRoot: null, /** - * An entity type. - * @property {string} + * A name. + * + * @type {string} + * @public */ name: null, @@ -93,7 +142,7 @@ define('model', [], function () { /** * Definitions. - * @property {?Object} + * @type {?Object} */ defs: null, diff --git a/client/src/router.js b/client/src/router.js index 6c6716a16c..1f9fdee968 100644 --- a/client/src/router.js +++ b/client/src/router.js @@ -28,6 +28,14 @@ define('router', [], function () { + /** + * On route. + * + * @event Backbone.Router#route + * @param {string} name A route name. + * @param {any[]} args Arguments. + */ + /** * @class Espo.Router * @mixes Espo.Events @@ -135,7 +143,7 @@ define('router', [], function () { * Whether a confirm-leave-out was set. * * @public - * @property {boolean} + * @type {boolean} */ confirmLeaveOut: false, @@ -143,24 +151,24 @@ define('router', [], function () { * Whether back has been processed. * * @public - * @property {boolean} + * @type {boolean} */ backProcessed: false, /** - * @property {string} + * @type {string} * @internal */ confirmLeaveOutMessage: 'Are you sure?', /** - * @property {string} + * @type {string} * @internal */ confirmLeaveOutConfirmText: 'Yes', /** - * @property {string} + * @type {string} * @internal */ confirmLeaveOutCancelText: 'No', @@ -243,13 +251,13 @@ define('router', [], function () { }, /** - * @callback Espo.Router.checkConfirmLeaveOutCallback + * @callback Espo.Router~checkConfirmLeaveOutCallback */ /** * Process confirm-leave-out. * - * @param {Espo.Router.checkConfirmLeaveOutCallback} callback Proceed if confirmed. + * @param {Espo.Router~checkConfirmLeaveOutCallback} callback Proceed if confirmed. * @param {?Object} [context] A context. * @param {boolean} [navigateBack] To navigate back if not confirmed. */ diff --git a/client/src/view.js b/client/src/view.js index dc5bdefd50..0ed6bc9bf0 100644 --- a/client/src/view.js +++ b/client/src/view.js @@ -33,27 +33,38 @@ define('view', [], function () { * * @class Espo.View * @extends Bull.View - * - * @property {?Espo.Model} model - A model. - * @property {?Espo.Collection} collection - A collection. - * @property {Object} options - Passed options. */ return Bull.View.extend(/** @lends Espo.View.prototype */{ /** - * @callback Espo.View.actionHandlerCallback - * @param {jQuery.Event} e + * @callback Espo.View~actionHandlerCallback + * @param {jQuery.Event} e A DOM event. */ /** - * Add a DOM action event handler. + * A model. * + * @name model + * @type {?Espo.Model} + * @public + */ + + /** + * A collection. + * + * @name collection + * @type {?Espo.Collection} + * @public + */ + + /** + * Add a DOM button-action event handler. + * + * @deprecated Use the `events` property. * @param {string} action - * @param {Espo.View.actionHandlerCallback} handler + * @param {Espo.View~actionHandlerCallback} handler */ addActionHandler: function (action, handler) { - this.events = this.events || {}; - let fullAction = 'click button[data-action=\"'+action+'\"]'; this.events[fullAction] = handler; @@ -195,6 +206,8 @@ define('view', [], function () { }, /** + * Get the session-storage-util. + * * @returns {Espo.SessionStorage} */ getSessionStorage: function () { @@ -303,7 +316,7 @@ define('view', [], function () { /** * Set a page title. * - * @param {string} title + * @param {string} title A title. */ setPageTitle: function (title) { this.getHelper().pageTitle.setTitle(title); @@ -323,6 +336,7 @@ define('view', [], function () { /** * Get a base path. + * * @returns {string} */ getBasePath: function () { @@ -332,6 +346,7 @@ define('view', [], function () { /** * Ajax request. * + * @deprecated Use `Espo.Ajax`. * @param {string} url An URL. * @param {string} type A method. * @param {any} [data] Data. @@ -357,6 +372,7 @@ define('view', [], function () { /** * POST request. * + * @deprecated Use `Espo.Ajax.postRequest`. * @param {string} url An URL. * @param {any} [data] Data. * @param {Object} [options] Options. @@ -373,6 +389,7 @@ define('view', [], function () { /** * PATCH request. * + * @deprecated Use `Espo.Ajax.patchRequest`. * @param {string} url An URL. * @param {any} [data] Data. * @param {Object} [options] Options. @@ -389,6 +406,7 @@ define('view', [], function () { /** * PUT request. * + * @deprecated Use `Espo.Ajax.putRequest`. * @param {string} url An URL. * @param {any} [data] Data. * @param {Object} [options] Options. @@ -405,6 +423,7 @@ define('view', [], function () { /** * GET request. * + * @deprecated Use `Espo.Ajax.getRequest`. * @param {string} url An URL. * @param {any} [data] Data. * @param {Object} [options] Options. @@ -417,6 +436,7 @@ define('view', [], function () { /** * DELETE request. * + * @deprecated Use `Espo.Ajax.deleteRequest`. * @param {string} url An URL. * @param {any} [data] Data. * @param {Object} [options] Options. @@ -467,6 +487,6 @@ define('view', [], function () { noCancelButton: o.noCancelButton, backdrop: ('backdrop' in o) ? o.backdrop : true, }, callback, context); - } + }, }); });