From 94482ebd5c94006a930688d14971f90d1c898ba5 Mon Sep 17 00:00:00 2001 From: Andrea Fercia Date: Mon, 31 Aug 2026 11:36:29 +0200 Subject: [PATCH] Lint JSDocs part 4 --- src/js/media/views/attachment-compat.js | 2 +- src/js/media/views/attachment.js | 36 ++++++++++++++++---- src/js/media/views/attachment/details.js | 2 -- src/js/media/views/attachments/browser.js | 2 +- src/js/media/views/button-group.js | 4 ++- src/js/media/views/embed/url.js | 4 ++- src/js/media/views/focus-manager.js | 2 -- src/js/media/views/frame.js | 14 +++++--- src/js/media/views/frame/edit-attachments.js | 3 ++ src/js/media/views/frame/manage.js | 4 +++ src/js/media/views/media-details.js | 2 +- src/js/media/views/menu.js | 2 +- src/js/media/views/modal.js | 20 ++++++++++- src/js/media/views/priority-list.js | 14 ++++++-- src/js/media/views/toolbar.js | 4 ++- src/js/media/views/uploader/editor.js | 7 +++- src/js/media/views/uploader/inline.js | 12 +++++-- src/js/media/views/uploader/status.js | 16 +++++++-- src/js/media/views/uploader/window.js | 6 ++-- 19 files changed, 120 insertions(+), 36 deletions(-) diff --git a/src/js/media/views/attachment-compat.js b/src/js/media/views/attachment-compat.js index d24de569639bd..d9d8016d3bcfc 100644 --- a/src/js/media/views/attachment-compat.js +++ b/src/js/media/views/attachment-compat.js @@ -42,7 +42,7 @@ AttachmentCompat = View.extend(/** @lends wp.media.view.AttachmentCompat.prototy return View.prototype.dispose.apply( this, arguments ); }, /** - * @return {wp.media.view.AttachmentCompat} Returns itself to allow chaining. + * @return {void|wp.media.view.AttachmentCompat} Returns itself to allow chaining. */ render: function() { var compat = this.model.get('compat'); diff --git a/src/js/media/views/attachment.js b/src/js/media/views/attachment.js index 5761c959ea481..8a123d79de532 100644 --- a/src/js/media/views/attachment.js +++ b/src/js/media/views/attachment.js @@ -79,6 +79,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ this.listenTo( this.controller.states, 'attachment:compat:waiting attachment:compat:ready', this.updateSave ); }, /** + * Update the view after the model has been saved. + * * @return {wp.media.view.Attachment} Returns itself to allow chaining. */ dispose: function() { @@ -97,6 +99,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ return this; }, /** + * Renders the attachment view. + * * @return {wp.media.view.Attachment} Returns itself to allow chaining. */ render: function() { @@ -167,6 +171,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ }, /** + * Toggles the selection state of the attachment. + * * @param {Object} event */ toggleSelectionHandler: function( event ) { @@ -221,6 +227,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ this.controller.trigger( 'selection:toggle' ); }, /** + * Toggles the selection state of the attachment. + * * @param {Object} options */ toggleSelection: function( options ) { @@ -301,7 +309,9 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ this[ this.selected() ? 'select' : 'deselect' ](); }, /** - * @return {unresolved|boolean} + * Checks if the model is selected in the selection. + * + * @return {void|boolean} True if the model is selected in the selection, false otherwise. */ selected: function() { var selection = this.options.selection; @@ -310,6 +320,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ } }, /** + * Selects the model in the selection. + * * @param {Backbone.Model} model * @param {Backbone.Collection} collection */ @@ -339,6 +351,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ } }, /** + * Deselects the model in the selection. + * * @param {Backbone.Model} model * @param {Backbone.Collection} collection */ @@ -357,6 +371,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ .find( '.check' ).attr( 'tabindex', '-1' ); }, /** + * Updates the view to reflect whether the model is the single model in the selection. + * * @param {Backbone.Model} model * @param {Backbone.Collection} collection */ @@ -372,8 +388,10 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ this.$el.toggleClass( 'details', details === this.model ); }, /** + * Gets the image size object for the specified size. + * * @param {string} size - * @return {Object} + * @return {Object} Returns an object containing the image size information. */ imageSize: function( size ) { var sizes = this.model.get('sizes'), matched = false; @@ -405,6 +423,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ }; }, /** + * Update the model's setting with the value from the input. + * * @param {Object} event */ updateSetting: function( event ) { @@ -456,6 +476,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ }); }, /** + * Updates the view's save status. + * * @param {string} status * @return {wp.media.view.Attachment} Returns itself to allow chaining. */ @@ -498,6 +520,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ } }, /** + * Removes the model from the collection. + * * @param {Object} event */ removeFromLibrary: function( event ) { @@ -513,11 +537,11 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{ }, /** - * Add the model if it isn't in the selection, if it is in the selection, - * remove it. + * Adds the model if it isn't in the selection, if it is in the selection, + * removes it. * - * @param {[type]} event [description] - * @return {[type]} [description] + * @param {Object} event + * @return {void} */ checkClickHandler: function ( event ) { var selection = this.options.selection; diff --git a/src/js/media/views/attachment/details.js b/src/js/media/views/attachment/details.js index 8f450be793cfb..a4ed635b62442 100644 --- a/src/js/media/views/attachment/details.js +++ b/src/js/media/views/attachment/details.js @@ -33,8 +33,6 @@ Details = Attachment.extend(/** @lends wp.media.view.Attachment.Details.prototyp * * @since 5.5.0 * - * @param {MouseEvent} event A click event. - * * @return {void} */ copyAttachmentDetailsURLClipboard: function() { diff --git a/src/js/media/views/attachments/browser.js b/src/js/media/views/attachments/browser.js index 82b7359eb832a..889978eaf78ec 100644 --- a/src/js/media/views/attachments/browser.js +++ b/src/js/media/views/attachments/browser.js @@ -17,7 +17,7 @@ var View = wp.media.View, * @augments wp.Backbone.View * @augments Backbone.View * - * @param {object} [options] The options hash passed to the view. + * @param {Object} [options] The options hash passed to the view. * @param {boolean|string} [options.filters=false] Which filters to show in the browser's toolbar. * Accepts 'uploaded' and 'all'. * @param {boolean} [options.search=true] Whether to show the search interface in the diff --git a/src/js/media/views/button-group.js b/src/js/media/views/button-group.js index bf5fe968bc187..e0fd09b0d957d 100644 --- a/src/js/media/views/button-group.js +++ b/src/js/media/views/button-group.js @@ -35,7 +35,9 @@ ButtonGroup = wp.media.View.extend(/** @lends wp.media.view.ButtonGroup.prototyp }, /** - * @return {wp.media.view.ButtonGroup} + * Renders the button group. + * + * @return {wp.media.view.ButtonGroup} The button group. */ render: function() { this.$el.html( $( _.pluck( this.buttons, 'el' ) ).detach() ); diff --git a/src/js/media/views/embed/url.js b/src/js/media/views/embed/url.js index 701b2859518e1..42c620dda4530 100644 --- a/src/js/media/views/embed/url.js +++ b/src/js/media/views/embed/url.js @@ -39,7 +39,9 @@ EmbedUrl = View.extend(/** @lends wp.media.view.EmbedUrl.prototype */{ } }, /** - * @return {wp.media.view.EmbedUrl} Returns itself to allow chaining. + * Renders the view. + * + * @return {void|wp.media.view.EmbedUrl} Returns itself to allow chaining. */ render: function() { var $input = this.$input; diff --git a/src/js/media/views/focus-manager.js b/src/js/media/views/focus-manager.js index d79961b05b89c..36ef6a851b0da 100644 --- a/src/js/media/views/focus-manager.js +++ b/src/js/media/views/focus-manager.js @@ -218,8 +218,6 @@ var FocusManager = wp.media.View.extend(/** @lends wp.media.view.FocusManager.pr * * @since 5.3.0 * - * @param {Object} event jQuery event object. - * * @return {void} */ setupAriaTabs: function() { diff --git a/src/js/media/views/frame.js b/src/js/media/views/frame.js index 8805bc7de45e2..851557d9f3ccb 100644 --- a/src/js/media/views/frame.js +++ b/src/js/media/views/frame.js @@ -88,6 +88,10 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{ }, /** * Map activeMode collection events to the frame. + * + * @param {Backbone.Model} model + * @param {Backbone.Collection} collection + * @param {Object} options */ triggerModeEvents: function( model, collection, options ) { var collectionEvent, @@ -113,8 +117,8 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{ /** * Activate a mode on the frame. * - * @param string mode Mode ID. - * @return {this} Returns itself to allow chaining. + * @param {string} mode Mode ID. + * @return {void|this} Returns itself to allow chaining. */ activateMode: function( mode ) { // Bail if the mode is already active. @@ -130,7 +134,7 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{ /** * Deactivate a mode on the frame. * - * @param string mode Mode ID. + * @param {string} mode Mode ID. * @return {this} Returns itself to allow chaining. */ deactivateMode: function( mode ) { @@ -152,8 +156,8 @@ var Frame = wp.media.View.extend(/** @lends wp.media.view.Frame.prototype */{ /** * Check if a mode is enabled on the frame. * - * @param string mode Mode ID. - * @return bool + * @param {string} mode Mode ID. + * @return {boolean} True if the mode is active, false otherwise. */ isModeActive: function( mode ) { return Boolean( this.activeModes.where( { id: mode } ).length ); diff --git a/src/js/media/views/frame/edit-attachments.js b/src/js/media/views/frame/edit-attachments.js index f6bb4b8afa2cc..e3bc0d09e643b 100644 --- a/src/js/media/views/frame/edit-attachments.js +++ b/src/js/media/views/frame/edit-attachments.js @@ -207,6 +207,7 @@ EditAttachments = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.EditAtta /** * Rerender the view. + * @param {wp.media.model.Attachment} model The attachment model to render. */ rerender: function( model ) { this.stopListening( this.model ); @@ -285,6 +286,8 @@ EditAttachments = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.EditAtta * Respond to the keyboard events: Alt + right arrow, Alt + left arrow, * except when focus is in a form field. Requires the Alt modifier key to * avoid interfering with screen reader navigation. + * + * @param {Event} event The keyboard event. */ keyEvent: function( event ) { if ( ( 'INPUT' === event.target.nodeName || 'TEXTAREA' === event.target.nodeName || 'SELECT' === event.target.nodeName ) && ! event.target.disabled ) { diff --git a/src/js/media/views/frame/manage.js b/src/js/media/views/frame/manage.js index ea16637fdf7a5..2fb32e09eac74 100644 --- a/src/js/media/views/frame/manage.js +++ b/src/js/media/views/frame/manage.js @@ -196,6 +196,8 @@ Manage = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Manage.prototype /** * Click handler for the `Add New` button. + * + * @param {Event} event The click event. */ addNewClickHandler: function( event ) { event.preventDefault(); @@ -208,6 +210,8 @@ Manage = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Manage.prototype /** * Open the Edit Attachment modal. + * + * @param {wp.media.model.Attachment} model The attachment model to edit. */ openEditAttachmentModal: function( model ) { // Create a new EditAttachment frame, passing along the library and the attachment model. diff --git a/src/js/media/views/media-details.js b/src/js/media/views/media-details.js index 19b1fb0d9c253..eab736e5c8303 100644 --- a/src/js/media/views/media-details.js +++ b/src/js/media/views/media-details.js @@ -148,7 +148,7 @@ MediaDetails = AttachmentDisplay.extend(/** @lends wp.media.view.MediaDetails.pr * When multiple players in the DOM contain the same src, things get weird. * * @param {HTMLElement} elem - * @return {HTMLElement} + * @return {HTMLElement} The prepared element. */ prepareSrc : function( elem ) { var i = MediaDetails.instances++; diff --git a/src/js/media/views/menu.js b/src/js/media/views/menu.js index cf967c83bb4f6..97f4f0f436ab8 100644 --- a/src/js/media/views/menu.js +++ b/src/js/media/views/menu.js @@ -48,7 +48,7 @@ Menu = PriorityList.extend(/** @lends wp.media.view.Menu.prototype */{ /** * @param {Object} options * @param {string} id - * @return {wp.media.View} + * @return {wp.media.View} The view instance. */ toView: function( options, id ) { options = options || {}; diff --git a/src/js/media/views/modal.js b/src/js/media/views/modal.js index cfc396bf8039b..29150515a45cd 100644 --- a/src/js/media/views/modal.js +++ b/src/js/media/views/modal.js @@ -37,7 +37,9 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ }); }, /** - * @return {Object} + * Prepares the data for the modal template. + * + * @return {Object} The prepared data. */ prepare: function() { return { @@ -47,6 +49,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ }, /** + * Attaches the modal to the DOM and triggers the ready event. + * * @return {wp.media.view.Modal} Returns itself to allow chaining. */ attach: function() { @@ -68,6 +72,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ }, /** + * Detaches the modal from the DOM and triggers the detach event. + * * @return {wp.media.view.Modal} Returns itself to allow chaining. */ detach: function() { @@ -81,6 +87,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ }, /** + * Opens the modal and triggers the open event. + * * @return {wp.media.view.Modal} Returns itself to allow chaining. */ open: function() { @@ -124,6 +132,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ }, /** + * Closes the modal and triggers the close event. + * * @param {Object} options * @return {wp.media.view.Modal} Returns itself to allow chaining. */ @@ -167,12 +177,16 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ return this; }, /** + * Closes the modal and triggers the escape event. + * * @return {wp.media.view.Modal} Returns itself to allow chaining. */ escape: function() { return this.close({ escape: true }); }, /** + * Handles the escape key press event to close the modal. + * * @param {Object} event */ escapeHandler: function( event ) { @@ -204,6 +218,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ }, /** + * Sets the content of the modal by registering views to the '.media-modal-content' selector. + * * @param {Array|Object} content Views to register to '.media-modal-content' * @return {wp.media.view.Modal} Returns itself to allow chaining. */ @@ -229,6 +245,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{ return this; }, /** + * Handles keydown events within the modal. + * * @param {Object} event */ keydown: function( event ) { diff --git a/src/js/media/views/priority-list.js b/src/js/media/views/priority-list.js index 65e7cde20ddd2..28a83f753d78b 100644 --- a/src/js/media/views/priority-list.js +++ b/src/js/media/views/priority-list.js @@ -22,6 +22,8 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr } }, /** + * Adds a view to the list, sorted by its priority. + * * @param {string} id * @param {wp.media.View|Object} view * @param {Object} options @@ -65,15 +67,19 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr return this; }, /** + * Retrieves a view by its ID. + * * @param {string} id - * @return {wp.media.View} + * @return {wp.media.View} Returns the view if found, otherwise undefined. */ get: function( id ) { return this._views[ id ]; }, /** + * Removes a view by its ID. + * * @param {string} id - * @return {wp.media.view.PriorityList} + * @return {wp.media.view.PriorityList} Returns itself to allow chaining. */ unset: function( id ) { var view = this.get( id ); @@ -86,8 +92,10 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr return this; }, /** + * Creates a view from an object of options. + * * @param {Object} options - * @return {wp.media.View} + * @return {wp.media.View} Returns the created view. */ toView: function( options ) { return new wp.media.View( options ); diff --git a/src/js/media/views/toolbar.js b/src/js/media/views/toolbar.js index ff98d13b0a316..c22dfc53dbfcd 100644 --- a/src/js/media/views/toolbar.js +++ b/src/js/media/views/toolbar.js @@ -109,8 +109,10 @@ Toolbar = View.extend(/** @lends wp.media.view.Toolbar.prototype */{ return this; }, /** + * Retrieves a view by its ID. + * * @param {string} id - * @return {wp.media.view.Button} + * @return {wp.media.view.Button} The view associated with the given ID, or undefined if no view is found. */ get: function( id ) { return this._views[ id ]; diff --git a/src/js/media/views/uploader/editor.js b/src/js/media/views/uploader/editor.js index 824d7253f80d8..4ea1c310b73c9 100644 --- a/src/js/media/views/uploader/editor.js +++ b/src/js/media/views/uploader/editor.js @@ -28,6 +28,8 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype * /** * Bind drag'n'drop events to callbacks. + * + * @return {wp.media.view.EditorUploader} Chainable. */ initialize: function() { this.initialized = false; @@ -64,7 +66,7 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype * /** * Check browser support for drag'n'drop. * - * @return {boolean} + * @return {boolean} True if the browser supports drag'n'drop, false otherwise. */ browserSupport: function() { var supports = false, div = document.createElement('div'); @@ -130,6 +132,7 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype * * and upload the file immediately. * * @param {jQuery.Event} event The 'drop' event. + * @return {void|boolean} False to prevent default behavior. */ drop: function( event ) { var $wrap, uploadView; @@ -174,6 +177,8 @@ EditorUploader = View.extend(/** @lends wp.media.view.EditorUploader.prototype * /** * Add the files to the uploader. + * + * @return {wp.media.view.EditorUploader} Chainable. */ addFiles: function() { if ( this.files.length ) { diff --git a/src/js/media/views/uploader/inline.js b/src/js/media/views/uploader/inline.js index 992d2eed02542..eedca1aa24d03 100644 --- a/src/js/media/views/uploader/inline.js +++ b/src/js/media/views/uploader/inline.js @@ -60,11 +60,13 @@ UploaderInline = View.extend(/** @lends wp.media.view.UploaderInline.prototype * return data; }, /** + * Disposes of the inline uploader and its associated views. + * * @return {wp.media.view.UploaderInline} Returns itself to allow chaining. */ dispose: function() { if ( this.disposing ) { - /** + /* * call 'dispose' directly on the parent class */ return View.prototype.dispose.apply( this, arguments ); @@ -79,10 +81,12 @@ UploaderInline = View.extend(/** @lends wp.media.view.UploaderInline.prototype * return this.remove(); }, /** + * Disposes of the inline uploader and its associated views. + * * @return {wp.media.view.UploaderInline} Returns itself to allow chaining. */ remove: function() { - /** + /* * call 'remove' directly on the parent class */ var result = View.prototype.remove.apply( this, arguments ); @@ -99,7 +103,9 @@ UploaderInline = View.extend(/** @lends wp.media.view.UploaderInline.prototype * } }, /** - * @return {wp.media.view.UploaderInline} + * Replaces the placeholder with the uploader browser and refreshes the uploader. + * + * @return {void|wp.media.view.UploaderInline} Returns itself to allow chaining. */ ready: function() { var $browser = this.options.$browser, diff --git a/src/js/media/views/uploader/status.js b/src/js/media/views/uploader/status.js index f629e0a34365f..370f4df223ece 100644 --- a/src/js/media/views/uploader/status.js +++ b/src/js/media/views/uploader/status.js @@ -33,11 +33,13 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype * this.errors.on( 'add', this.error, this ); }, /** - * @return {wp.media.view.UploaderStatus} + * Disposes of the uploader status and its associated views. + * + * @return {wp.media.view.UploaderStatus} Returns the instance of the UploaderStatus view. */ dispose: function() { wp.Uploader.queue.off( null, null, this ); - /** + /* * call 'dispose' directly on the parent class */ View.prototype.dispose.apply( this, arguments ); @@ -103,14 +105,19 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype * } }, /** + * Escapes the filename to prevent XSS attacks. + * * @param {string} filename - * @return {string} + * @return {string} Escaped filename. */ filename: function( filename ) { return _.escape( filename ); }, /** + * Handles an error event from the uploader queue. + * * @param {Backbone.Model} error + * @return {void} */ error: function( error ) { var statusError = new wp.media.view.UploaderStatusError( { @@ -131,6 +138,9 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype * }, 1500 ); }, + /** + * Dismisses the error messages and resets the uploader errors. + */ dismiss: function() { var errors = this.views.get('.upload-errors'); diff --git a/src/js/media/views/uploader/window.js b/src/js/media/views/uploader/window.js index 84b158f7cce61..0cd97f7c9dd76 100644 --- a/src/js/media/views/uploader/window.js +++ b/src/js/media/views/uploader/window.js @@ -13,11 +13,11 @@ var $ = jQuery, * @augments wp.Backbone.View * @augments Backbone.View * - * @param {object} [options] Options hash passed to the view. - * @param {object} [options.uploader] Uploader properties. + * @param {Object} [options] Options hash passed to the view. + * @param {Object} [options.uploader] Uploader properties. * @param {jQuery} [options.uploader.browser] * @param {jQuery} [options.uploader.dropzone] jQuery collection of the dropzone. - * @param {object} [options.uploader.params] + * @param {Object} [options.uploader.params] */ UploaderWindow = wp.media.View.extend(/** @lends wp.media.view.UploaderWindow.prototype */{ tagName: 'div',