Commit d9b6e3d788 for wordpress.org
commit d9b6e3d7888717a8f804fc121da658d592927b46
Author: afercia <afercia@git.wordpress.org>
Date: Fri Sep 11 06:30:52 2026 +0000
General: Enable the JSDoc rule require-param-description.
Enables the JSDoc rule `require-param-description` and fixes all the reported violations.
Part of the effort to improve JS inline documentation for 7.2.
Developed in https://github.com/WordPress/wordpress-develop/pull/13475
Props afercia, westonruter.
See #66033.
Built from https://develop.svn.wordpress.org/trunk@63598
git-svn-id: http://core.svn.wordpress.org/trunk@62774 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-admin/js/dashboard.js b/wp-admin/js/dashboard.js
index 31c9cd7cb1..595133d790 100644
--- a/wp-admin/js/dashboard.js
+++ b/wp-admin/js/dashboard.js
@@ -703,7 +703,7 @@ jQuery( function( $ ) {
*
* @since 5.5.2
*
- * @param {number} startTimestamp
+ * @param {number} startTimestamp The start timestamp of the event.
*
* @return {number} The offset from UTC in minutes, with the sign flipped to be more intuitive.
*/
@@ -716,7 +716,7 @@ jQuery( function( $ ) {
*
* @since 5.5.2
*
- * @param {number} startTimestamp
+ * @param {number} startTimestamp The start timestamp of the event.
*
* @return {string} A short time zone name, like `PST`, or a string like `GMT+5` if the abbreviation can't be determined.
*/
diff --git a/wp-admin/js/postbox.js b/wp-admin/js/postbox.js
index b6d1b6569d..1f101d3fd1 100644
--- a/wp-admin/js/postbox.js
+++ b/wp-admin/js/postbox.js
@@ -246,10 +246,10 @@
*
* @memberof postboxes
*
- * @param {string} page The page we are currently on.
- * @param {Object} [args]
- * @param {Function} args.pbshow A callback that is called when a postbox opens.
- * @param {Function} args.pbhide A callback that is called when a postbox closes.
+ * @param {string} page The page we are currently on.
+ * @param {Object} [args] Optional arguments for the postbox toggles.
+ * @param {Function} [args.pbshow] A callback that is called when a postbox opens.
+ * @param {Function} [args.pbhide] A callback that is called when a postbox closes.
* @return {void}
*/
add_postbox_toggles : function (page, args) {
diff --git a/wp-admin/js/site-health.js b/wp-admin/js/site-health.js
index dc9107a3eb..0a1b052e56 100644
--- a/wp-admin/js/site-health.js
+++ b/wp-admin/js/site-health.js
@@ -350,8 +350,8 @@ jQuery( function( $ ) {
/**
* Add the details of a failed asynchronous test to the list of test results.
*
- * @param {string} url
- * @param {string} description
+ * @param {string} url The URL of the failed test.
+ * @param {string} description The description of the failed test.
* @since 5.6.0
*/
function addFailedSiteHealthCheckNotice( url, description ) {
diff --git a/wp-admin/js/updates.js b/wp-admin/js/updates.js
index 22e7ac886f..7c971f4bb7 100644
--- a/wp-admin/js/updates.js
+++ b/wp-admin/js/updates.js
@@ -241,7 +241,7 @@
*
* @since 4.6.0
*
- * @param {Object} data
+ * @param {Object} data The data for the admin notice.
* @param {*} [data.selector] Optional. Selector of an element to be replaced with the admin notice.
* @param {string} [data.id] Optional. Unique id that will be used as the notice's id attribute.
* @param {string} [data.className] Optional. Class names that will be used in the admin notice.
@@ -334,7 +334,7 @@
*
* @since 4.6.0
*
- * @param {Object} response
+ * @param {Object} response The response object from the Ajax request.
* @param {Array} [response.debug] Optional. Debug information.
* @param {string} [response.errorCode] Optional. Error code for an error that occurred.
*/
@@ -1594,7 +1594,7 @@
* @since 4.6.0
* @since 5.5.0 Auto-update "time to next update" text cleared.
*
- * @param {Object} response
+ * @param {Object} response The response object from the Ajax request.
* @param {string} response.slug Slug of the theme to be updated.
* @param {Object} response.theme Updated theme.
* @param {string} response.oldVersion Old version of the theme.
@@ -1709,7 +1709,7 @@
*
* @since 4.6.0
*
- * @param {Object} args
+ * @param {Object} args The arguments for the theme installation request.
* @param {string} args.slug Theme stylesheet.
* @param {installThemeSuccess} args.success Optional. Success callback. Default: wp.updates.installThemeSuccess
* @param {installThemeError} args.error Optional. Error callback. Default: wp.updates.installThemeError
@@ -1901,7 +1901,7 @@
*
* @since 4.6.0
*
- * @param {Object} args
+ * @param {Object} args The arguments for the theme deletion request.
* @param {string} args.slug Theme stylesheet.
* @param {deleteThemeSuccess} args.success Optional. Success callback. Default: wp.updates.deleteThemeSuccess
* @param {deleteThemeError} args.error Optional. Error callback. Default: wp.updates.deleteThemeError
diff --git a/wp-includes/js/heartbeat.js b/wp-includes/js/heartbeat.js
index e7abe77bb3..e816959bda 100644
--- a/wp-includes/js/heartbeat.js
+++ b/wp-includes/js/heartbeat.js
@@ -244,8 +244,8 @@
/**
* Handles pageshow event, specifically when page navigation is restored from back/forward cache.
*
- * @param {jQuery.Event} event
- * @param {PageTransitionEvent} event.originalEvent
+ * @param {JQuery.Event} event The jQuery event object.
+ * @param {PageTransitionEvent} event.originalEvent The original PageTransitionEvent object.
*/
function ( event ) {
if ( event.originalEvent.persisted ) {
diff --git a/wp-includes/js/media-audiovideo.js b/wp-includes/js/media-audiovideo.js
index 5370d09603..735c0955dc 100644
--- a/wp-includes/js/media-audiovideo.js
+++ b/wp-includes/js/media-audiovideo.js
@@ -604,7 +604,7 @@ MediaDetails = AttachmentDisplay.extend(/** @lends wp.media.view.MediaDetails.pr
*
* @fires wp.media.view.MediaDetails#media:setting:remove
*
- * @param {Event} e
+ * @param {JQuery.Event} e The jQuery event object.
*/
removeSetting : function(e) {
var wrap = $( e.currentTarget ).parent(), setting;
@@ -637,7 +637,7 @@ MediaDetails = AttachmentDisplay.extend(/** @lends wp.media.view.MediaDetails.pr
/**
* Adds a source to the media details view.
*
- * @param {JQuery.Event} e The event object.
+ * @param {JQuery.Event} e The jQuery event object.
*/
addSource : function( e ) {
this.controller.lastMime = $( e.currentTarget ).data( 'mime' );
@@ -727,7 +727,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
+ * @param {HTMLElement} elem The HTML element containing the media sources to be prepared.
* @return {HTMLElement} The prepared element.
*/
prepareSrc : function( elem ) {
diff --git a/wp-includes/js/media-editor.js b/wp-includes/js/media-editor.js
index bec97f27f0..b6357520db 100644
--- a/wp-includes/js/media-editor.js
+++ b/wp-includes/js/media-editor.js
@@ -341,7 +341,7 @@
*
* @class wp.media.collection
*
- * @param {Object} attributes
+ * @param {Object} attributes The attributes for the media collection.
*/
wp.media.collection = function(attributes) {
var collections = {};
@@ -786,8 +786,8 @@
* Setup 'workflow' and add to the 'workflows' cache. 'open' can
* subsequently be called upon it.
*
- * @param {string} id A slug used to identify the workflow.
- * @param {Object} [options={}]
+ * @param {string} id A slug used to identify the workflow.
+ * @param {Object} [options={}] The options for the media workflow.
*
* @this wp.media.editor
*
@@ -1001,7 +1001,7 @@
/**
* Called when 'Insert From URL' source is not an image. Example: YouTube url.
*
- * @param {Object} embed
+ * @param {Object} embed The embed object containing the link URL and link text.
* @return {Promise} A promise that resolves when the link has been sent to the editor.
*/
link: function( embed ) {
@@ -1018,7 +1018,7 @@
* Opens a workflow.
*
* @param {string} [id=undefined] Optional. A slug used to identify the workflow.
- * @param {Object} [options={}]
+ * @param {Object} [options={}] The options for the media workflow.
*
* @this wp.media.editor
*
diff --git a/wp-includes/js/media-models.js b/wp-includes/js/media-models.js
index e3f3fdba54..8cda66a71a 100644
--- a/wp-includes/js/media-models.js
+++ b/wp-includes/js/media-models.js
@@ -20,9 +20,9 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp
* Triggered when attachment details change
* Overrides Backbone.Model.sync
*
- * @param {string} method
- * @param {wp.media.model.Attachment} model
- * @param {Object} [options={}]
+ * @param {string} method The method to be performed: 'read', 'update', or 'delete'.
+ * @param {wp.media.model.Attachment} model The attachment model being synced.
+ * @param {Object} [options={}] Optional. Additional options for the sync operation.
*
* @return {jQuery.Promise} A jQuery Promise that is resolved or rejected based on the success of the sync operation.
*/
@@ -150,7 +150,7 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp
*
* @static
*
- * @param {Object} attrs
+ * @param {Object} attrs The attributes for the new attachment model.
* @return {wp.media.model.Attachment} The newly created attachment model.
*/
create: function( attrs ) {
@@ -164,8 +164,8 @@ Attachment = Backbone.Model.extend(/** @lends wp.media.model.Attachment.prototyp
* it returns the specified attachment.
*
* @static
- * @param {string} id A string used to identify a model.
- * @param {Backbone.Model|undefined} attachment
+ * @param {string} id A string used to identify a model.
+ * @param {Backbone.Model|undefined} attachment The attachment model to retrieve or create.
* @return {wp.media.model.Attachment}
*/
get: _.memoize( function( id, attachment ) {
@@ -214,8 +214,8 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
/**
* Initializes the Attachments collection.
*
- * @param {Array} [models=[]] Array of models used to populate the collection.
- * @param {Object} [options={}]
+ * @param {Array} [models=[]] Optional. Array of models used to populate the collection.
+ * @param {Object} [options={}] Optional. Additional options for the collection.
*/
initialize: function( models, options ) {
var normalizedOrder;
@@ -265,8 +265,8 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
*
* @access private
*
- * @param {Backbone.Model} model
- * @param {string} orderby
+ * @param {Backbone.Model} model The model that triggered the change.
+ * @param {string} orderby The new orderby value.
*/
_changeOrderby: function( model, orderby ) {
// If a different comparator is defined, bail.
@@ -285,8 +285,8 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
*
* @access private
*
- * @param {Backbone.Model} model
- * @param {boolean} query
+ * @param {Backbone.Model} model The model that triggered the change.
+ * @param {boolean} query The new query value.
*/
_changeQuery: function( model, query ) {
if ( query ) {
@@ -301,7 +301,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
*
* @access private
*
- * @param {Backbone.Model} model
+ * @param {Backbone.Model} model The model that triggered the change.
*/
_changeFilteredProps: function( model ) {
// If this is a query, updating the collection will be handled by
@@ -347,7 +347,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
/**
* Checks whether an attachment is valid.
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to validate.
* @return {boolean} True if the attachment is valid, false otherwise.
*/
validator: function( attachment ) {
@@ -362,8 +362,8 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
/**
* Adds or removes an attachment to the collection depending on its validity.
*
- * @param {wp.media.model.Attachment} attachment
- * @param {Object} options
+ * @param {wp.media.model.Attachment} attachment The attachment to validate and potentially add or remove.
+ * @param {Object} options Additional options for the operation.
* @return {wp.media.model.Attachments} Returns itself to allow chaining.
*/
validate: function( attachment, options ) {
@@ -382,8 +382,8 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
/**
* Adds or removes all attachments from another collection depending on each one's validity.
*
- * @param {wp.media.model.Attachments} attachments
- * @param {Object} [options={}]
+ * @param {wp.media.model.Attachments} attachments The attachments collection to validate against.
+ * @param {Object} [options={}] Additional options for the operation.
*
* @fires wp.media.model.Attachments#reset
*
@@ -465,9 +465,9 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
*
* @access private
*
- * @param {wp.media.model.Attachments} attachment
- * @param {wp.media.model.Attachments} attachments
- * @param {Object} options
+ * @param {wp.media.model.Attachments} attachment The attachment to validate.
+ * @param {wp.media.model.Attachments} attachments The attachments collection the attachment belongs to.
+ * @param {Object} options Additional options for the operation.
*
* @return {wp.media.model.Attachments} Returns itself to allow chaining.
*/
@@ -485,8 +485,8 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
*
* @access private
*
- * @param {wp.media.model.Attachments} attachments
- * @param {Object} options
+ * @param {wp.media.model.Attachments} attachments The attachments collection to validate against.
+ * @param {Object} options Additional options for the operation.
* @return {wp.media.model.Attachments} Returns itself to allow chaining.
*/
_validateAllHandler: function( attachments, options ) {
@@ -539,7 +539,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* and forwards to its `more` method. This collection class doesn't have
* server persistence by itself.
*
- * @param {Object} options
+ * @param {Object} options Additional options for the operation.
* @return {Promise} A promise that resolves when the request is complete.
*/
more: function( options ) {
@@ -608,7 +608,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* the collection items.
*
* @param {Object|Array} response The raw response Object/Array.
- * @param {Object} xhr
+ * @param {Object} xhr The XMLHttpRequest object.
* @return {Array} The array of model attributes to be added to the collection
*/
parse: function( response, xhr ) {
@@ -689,9 +689,9 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* Used as the default comparator for instances of wp.media.model.Attachments
* and its subclasses. @see wp.media.model.Attachments._changeOrderby().
*
- * @param {Backbone.Model} a
- * @param {Backbone.Model} b
- * @param {Object} options
+ * @param {Backbone.Model} a The first attachment model to compare.
+ * @param {Backbone.Model} b The second attachment model to compare.
+ * @param {Object} options Additional options for the comparison.
* @return {number} -1 if the first model should come before the second,
* 0 if they are of the same rank and
* 1 if the first model should come after.
@@ -726,7 +726,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* Note that this client-side searching is *not* equivalent
* to our server-side searching.
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to filter based on the search query.
*
* @this wp.media.model.Attachments
*
@@ -746,7 +746,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* Filters attachments based on their type.
*
* @static
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to filter based on its type.
*
* @this wp.media.model.Attachments
*
@@ -775,7 +775,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* Filters attachments based on their uploadedTo property.
*
* @static
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to filter based on its uploadedTo property.
*
* @this wp.media.model.Attachments
*
@@ -793,7 +793,7 @@ var Attachments = Backbone.Collection.extend(/** @lends wp.media.model.Attachmen
* Filters attachments based on their status property.
*
* @static
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to filter based on its status property.
*
* @this wp.media.model.Attachments
*
@@ -1006,7 +1006,7 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
* Initializes the Query collection.
*
* @param {Array} [models=[]] Array of initial models to populate the collection.
- * @param {Object} [options={}]
+ * @param {Object} [options={}] Additional options for initializing the query.
*/
initialize: function( models, options ) {
var allowed;
@@ -1077,7 +1077,7 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
/**
* Fetch more attachments from the server for the collection.
*
- * @param {Object} [options={}]
+ * @param {Object} [options={}] Additional options for fetching more attachments.
* @return {Promise} A promise that resolves when the fetch is complete.
*/
more: function( options ) {
@@ -1105,9 +1105,9 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
* Overrides Backbone.Collection.sync
* Overrides wp.media.model.Attachments.sync
*
- * @param {string} method
- * @param {Backbone.Model} model
- * @param {Object} [options={}]
+ * @param {string} method The sync method to be used (e.g., 'read', 'create', 'update', 'delete').
+ * @param {Backbone.Model} model The model to be synced.
+ * @param {Object} [options={}] Additional options for syncing the query.
* @return {Promise} A promise that resolves when the sync is complete.
*/
sync: function( method, model, options ) {
@@ -1195,19 +1195,19 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
* @static
* @function
*
- * @param {Object} [props]
- * @param {Object} [props.order]
- * @param {Object} [props.orderby]
- * @param {Object} [props.include]
- * @param {Object} [props.exclude]
- * @param {Object} [props.s]
- * @param {Object} [props.post_mime_type]
- * @param {Object} [props.posts_per_page]
- * @param {Object} [props.menu_order]
- * @param {Object} [props.post_parent]
- * @param {Object} [props.post_status]
- * @param {Object} [props.author]
- * @param {Object} [options]
+ * @param {Object} [props] The properties to initialize the query with.
+ * @param {Object} [props.order] The order in which to sort the query results.
+ * @param {Object} [props.orderby] The property by which to order the query results.
+ * @param {Object} [props.include] The IDs of attachments to include in the query.
+ * @param {Object} [props.exclude] The IDs of attachments to exclude from the query.
+ * @param {Object} [props.s] The search term to filter attachments by.
+ * @param {Object} [props.post_mime_type] The MIME type to filter attachments by.
+ * @param {Object} [props.posts_per_page] The number of attachments to retrieve per page.
+ * @param {Object} [props.menu_order] The menu order to filter attachments by.
+ * @param {Object} [props.post_parent] The parent post ID to filter attachments by.
+ * @param {Object} [props.post_status] The status to filter attachments by.
+ * @param {Object} [props.author] The author ID to filter attachments by.
+ * @param {Object} [options] Additional options for the query.
*
* @return {wp.media.model.Query} A new Attachments Query collection.
*/
@@ -1221,8 +1221,8 @@ Query = Attachments.extend(/** @lends wp.media.model.Query.prototype */{
/**
* Creates and returns an Attachments Query collection given the properties.
*
- * @param {Object} [props]
- * @param {Object} [options]
+ * @param {Object} [props] The properties to initialize the query with.
+ * @param {Object} [options] Additional options for the query.
* @return {Query} A new Attachments Query collection.
*/
return function( props, options ) {
@@ -1310,8 +1310,8 @@ Selection = Attachments.extend(/** @lends wp.media.model.Selection.prototype */{
* Binds `single` instead of using the context argument to ensure
* it receives no parameters.
*
- * @param {Array} [models=[]] Array of models used to populate the collection.
- * @param {Object} [options={}]
+ * @param {Array} [models=[]] Array of models used to populate the collection.
+ * @param {Object} [options={}] Additional options for the selection.
*/
initialize: function( models, options ) {
/**
@@ -1327,8 +1327,8 @@ Selection = Attachments.extend(/** @lends wp.media.model.Selection.prototype */{
* If the workflow does not support multi-select, clear out the selection
* before adding a new attachment to it.
*
- * @param {Array} models
- * @param {Object} options
+ * @param {Array} models The models to add to the selection.
+ * @param {Object} options Additional options for adding the models.
* @return {wp.media.model.Attachment[]} The added attachments.
*/
add: function( models, options ) {
@@ -1344,7 +1344,7 @@ Selection = Attachments.extend(/** @lends wp.media.model.Selection.prototype */{
/**
* Fired when toggling (clicking on) an attachment in the modal.
*
- * @param {undefined|boolean|wp.media.model.Attachment} model
+ * @param {undefined|boolean|wp.media.model.Attachment} model The model to set as the single selection, or a boolean to clear it.
*
* @fires wp.media.model.Selection#selection:single
* @fires wp.media.model.Selection#selection:unsingle
@@ -1556,7 +1556,11 @@ _.extend( media, /** @lends wp.media */{
/**
* Scales a set of dimensions to fit within bounding dimensions.
*
- * @param {Object} dimensions
+ * @param {Object} dimensions The dimensions to scale.
+ * @param {number} dimensions.width The width to scale.
+ * @param {number} dimensions.height The height to scale.
+ * @param {number} dimensions.maxWidth The maxWidth to scale.
+ * @param {number} dimensions.maxHeight The maxHeight to scale.
* @return {Object} The scaled dimensions.
*/
fit: function( dimensions ) {
@@ -1602,9 +1606,9 @@ _.extend( media, /** @lends wp.media */{
* Truncates a string by injecting an ellipsis into the middle.
* Useful for filenames.
*
- * @param {string} string
- * @param {number} [length=30]
- * @param {string} [replacement=…]
+ * @param {string} string The string to truncate.
+ * @param {number} [length=30] The maximum length of the truncated string.
+ * @param {string} [replacement=…] The string to use as the ellipsis replacement.
* @return {string} The string, unless length is greater than string.length.
*/
truncate: function( string, length, replacement ) {
@@ -1648,7 +1652,7 @@ Attachments.all = new Attachments();
*
* Shorthand for creating a new Attachments Query.
*
- * @param {Object} [props]
+ * @param {Object} [props] The properties to filter the attachments by.
* @return {wp.media.model.Attachments} A collection of attachments matching the query.
*/
media.query = function( props ) {
diff --git a/wp-includes/js/media-views.js b/wp-includes/js/media-views.js
index 356303a4c3..d8020eaa4e 100644
--- a/wp-includes/js/media-views.js
+++ b/wp-includes/js/media-views.js
@@ -741,7 +741,7 @@ Embed = wp.media.controller.State.extend(/** @lends wp.media.controller.Embed.pr
/**
* Try scanning the embed as an image to discover its dimensions.
*
- * @param {Object} attributes
+ * @param {Object} attributes The attributes for the embed scan.
*/
scanImage: function( attributes ) {
var frame = this.frame,
@@ -1456,7 +1456,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar
*
* @since 3.5.0
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment for which to create display settings.
* @return {Backbone.Model} A model representing the display settings for the attachment.
*/
display: function( attachment ) {
@@ -1473,7 +1473,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar
*
* @since 3.6.0
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment for which to get the default display settings.
* @return {Object} The default display settings for the attachment.
*/
defaultDisplaySettings: function( attachment ) {
@@ -1494,7 +1494,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar
*
* @since 4.4.1
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to check.
* @return {boolean} True if the attachment is an image, false otherwise.
*/
isImageAttachment: function( attachment ) {
@@ -1511,7 +1511,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar
*
* @since 3.6.0
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment to check.
* @return {boolean} True if the attachment can be embedded, false otherwise.
*/
canEmbed: function( attachment ) {
@@ -1560,7 +1560,7 @@ Library = wp.media.controller.State.extend(/** @lends wp.media.controller.Librar
*
* @since 3.5.0
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment that was uploaded.
*/
uploading: function( attachment ) {
var content = this.frame.content;
@@ -1702,7 +1702,7 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{
*
* @since 3.5.0
*
- * @param {string} mode
+ * @param {string} mode The mode to activate on the region.
*
* @fires Region#activate
* @fires Region#deactivate
@@ -1741,7 +1741,7 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{
*
* @since 3.5.0
*
- * @param {string} mode
+ * @param {string} mode The mode to render on the region.
*
* @fires Region#create
* @fires Region#render
@@ -1800,8 +1800,8 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{
*
* @since 3.5.0
*
- * @param {Array|Object} views
- * @param {Object} [options={}]
+ * @param {Array|Object} views The views to set on the region.
+ * @param {Object} [options={}] Optional. Additional options for setting the views on the region.
* @return {wp.Backbone.Subviews} Subviews is returned to allow chaining.
*/
set: function( views, options ) {
@@ -1816,7 +1816,7 @@ _.extend( Region.prototype,/** @lends wp.media.controller.Region.prototype */{
*
* @since 3.5.0
*
- * @param {string} event
+ * @param {string} event The event to trigger on the region.
* @return {undefined|wp.media.controller.Region} Returns itself to allow chaining.
*/
trigger: function( event ) {
@@ -2074,7 +2074,7 @@ _.extend( StateMachine.prototype, Backbone.Events,/** @lends wp.media.controller
*
* @since 3.5.0
*
- * @param {string} id
+ * @param {string} id The ID of the state to fetch. If omitted, the active state is returned.
* @return {wp.media.controller.State} Returns a State model from
* the StateMachine collection.
*/
@@ -2099,7 +2099,7 @@ _.extend( StateMachine.prototype, Backbone.Events,/** @lends wp.media.controller
*
* @since 3.5.0
*
- * @param {string} id
+ * @param {string} id The ID of the state to set as active.
*
* @fires wp.media.controller.State#deactivate
* @fires wp.media.controller.State#activate
@@ -2607,7 +2607,7 @@ AttachmentCompat = View.extend(/** @lends wp.media.view.AttachmentCompat.prototy
/**
* Prevents the default action of the event.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object associated with the action.
*/
preventDefault: function( event ) {
event.preventDefault();
@@ -2615,7 +2615,7 @@ AttachmentCompat = View.extend(/** @lends wp.media.view.AttachmentCompat.prototy
/**
* Saves the attachment compat data.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object associated with the action.
*/
save: function( event ) {
var data = {};
@@ -3160,7 +3160,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Toggles the selection state of the attachment.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object that triggered the selection toggle.
*/
toggleSelectionHandler: function( event ) {
var method;
@@ -3216,7 +3216,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Toggles the selection state of the attachment.
*
- * @param {Object} options
+ * @param {Object} options The options for toggling the selection state of the attachment.
*/
toggleSelection: function( options ) {
var collection = this.collection,
@@ -3309,8 +3309,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Selects the model in the selection.
*
- * @param {Backbone.Model} model
- * @param {Backbone.Collection} collection
+ * @param {Backbone.Model} model The model to select.
+ * @param {Backbone.Collection} collection The collection containing the model.
*/
select: function( model, collection ) {
var selection = this.options.selection,
@@ -3340,8 +3340,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Deselects the model in the selection.
*
- * @param {Backbone.Model} model
- * @param {Backbone.Collection} collection
+ * @param {Backbone.Model} model The model to deselect.
+ * @param {Backbone.Collection} collection The collection containing the model.
*/
deselect: function( model, collection ) {
var selection = this.options.selection;
@@ -3360,8 +3360,8 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Updates the view to reflect whether the model is the single model in the selection.
*
- * @param {Backbone.Model} model
- * @param {Backbone.Collection} collection
+ * @param {Backbone.Model} model The model to check for details.
+ * @param {Backbone.Collection} collection The collection containing the model.
*/
details: function( model, collection ) {
var selection = this.options.selection,
@@ -3377,7 +3377,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Gets the image size object for the specified size.
*
- * @param {string} size
+ * @param {string} size The desired image size.
* @return {Object} Returns an object containing the image size information.
*/
imageSize: function( size ) {
@@ -3412,7 +3412,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Update the model's setting with the value from the input.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object that triggered the setting update.
*/
updateSetting: function( event ) {
var $setting = $( event.target ).closest('[data-setting]'),
@@ -3465,7 +3465,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Updates the view's save status.
*
- * @param {string} status
+ * @param {string} status The new save status to apply to the view.
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
updateSave: function( status ) {
@@ -3509,7 +3509,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
/**
* Removes the model from the collection.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object that triggered the removal from the library.
*/
removeFromLibrary: function( event ) {
// Catch enter and space events.
@@ -3527,7 +3527,7 @@ Attachment = View.extend(/** @lends wp.media.view.Attachment.prototype */{
* Adds the model if it isn't in the selection, if it is in the selection,
* removes it.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object that triggered the selection toggle.
* @return {void}
*/
checkClickHandler: function ( event ) {
@@ -3563,8 +3563,8 @@ _.each({
* @memberOf wp.media.view.Attachment
* @instance
*
- * @param {Backbone.Model} model
- * @param {string} value
+ * @param {Backbone.Model} model The model containing the caption.
+ * @param {string} value The new caption value.
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
/**
@@ -3574,8 +3574,8 @@ _.each({
* @memberOf wp.media.view.Attachment
* @instance
*
- * @param {Backbone.Model} model
- * @param {string} value
+ * @param {Backbone.Model} model The model containing the title.
+ * @param {string} value The new title value.
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
/**
@@ -3585,8 +3585,8 @@ _.each({
* @memberOf wp.media.view.Attachment
* @instance
*
- * @param {Backbone.Model} model
- * @param {string} value
+ * @param {Backbone.Model} model The model containing the artist.
+ * @param {string} value The new artist value.
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
/**
@@ -3596,8 +3596,8 @@ _.each({
* @memberOf wp.media.view.Attachment
* @instance
*
- * @param {Backbone.Model} model
- * @param {string} value
+ * @param {Backbone.Model} model The model containing the album.
+ * @param {string} value The new album value.
* @return {wp.media.view.Attachment} Returns itself to allow chaining.
*/
Attachment.prototype[ method ] = function( model, value ) {
@@ -4384,7 +4384,7 @@ Attachments = View.extend(/** @lends wp.media.view.Attachments.prototype */{
*
* @since 3.5.0
*
- * @param {wp.media.model.Attachment} attachment
+ * @param {wp.media.model.Attachment} attachment The attachment model for which to create a view.
*
* @return {wp.media.View} The created view.
*/
@@ -5438,7 +5438,7 @@ var Button = wp.media.View.extend(/** @lends wp.media.view.Button.prototype */{
/**
* Handles the click event.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object for the click action.
*/
click: function( event ) {
if ( '#' === this.attributes.href ) {
@@ -5653,7 +5653,7 @@ var Embed = wp.media.View.extend(/** @lends wp.media.view.Embed.prototype */{
/**
* Sets the settings for the embed view.
*
- * @param {Object} view
+ * @param {Object} view The view object to be set as the settings for the embed view.
*/
settings: function( view ) {
if ( this._settings ) {
@@ -6381,9 +6381,9 @@ 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
+ * @param {Backbone.Model} model The model that triggered the event.
+ * @param {Backbone.Collection} collection The collection to which the model belongs.
+ * @param {Object} options The options object associated with the event.
*/
triggerModeEvents: function( model, collection, options ) {
var collectionEvent,
@@ -6917,7 +6917,7 @@ Post = Select.extend(/** @lends wp.media.view.MediaFrame.Post.prototype */{
/**
* Handles the main menu for the frame.
*
- * @param {wp.Backbone.View} view
+ * @param {wp.Backbone.View} view The menu view for the main menu.
*/
mainMenu: function( view ) {
view.set({
@@ -6948,7 +6948,7 @@ Post = Select.extend(/** @lends wp.media.view.MediaFrame.Post.prototype */{
/**
* Handles the gallery menu for the frame.
*
- * @param {wp.Backbone.View} view
+ * @param {wp.Backbone.View} view The menu view for the gallery menu.
*/
galleryMenu: function( view ) {
var lastState = this.lastState(),
@@ -6980,7 +6980,7 @@ Post = Select.extend(/** @lends wp.media.view.MediaFrame.Post.prototype */{
/**
* Handles the playlist menu for the frame.
*
- * @param {wp.Backbone.View} view The menu view.
+ * @param {wp.Backbone.View} view The menu view for the playlist menu.
*/
playlistMenu: function( view ) {
var lastState = this.lastState(),
@@ -7608,7 +7608,7 @@ Select = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Select.prototype
/**
* Render callback for the router region in the `browse` mode.
*
- * @param {wp.media.view.Router} routerView
+ * @param {wp.media.view.Router} routerView The router view for the `browse` mode.
*/
browseRouter: function( routerView ) {
routerView.set({
@@ -7626,7 +7626,7 @@ Select = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Select.prototype
/**
* Render callback for the content region in the `browse` mode.
*
- * @param {wp.media.controller.Region} contentRegion
+ * @param {wp.media.controller.Region} contentRegion The content region for the `browse` mode.
*/
browseContent: function( contentRegion ) {
var state = this.state();
@@ -7667,8 +7667,8 @@ Select = MediaFrame.extend(/** @lends wp.media.view.MediaFrame.Select.prototype
/**
* Toolbars
*
- * @param {Object} toolbar
- * @param {Object} [options={}]
+ * @param {Object} toolbar The toolbar object for the `select` mode.
+ * @param {Object} [options={}] The options for creating the select toolbar view.
* @this wp.media.controller.Region
*/
createSelectToolbar: function( toolbar, options ) {
@@ -8129,7 +8129,7 @@ MediaFrame = Frame.extend(/** @lends wp.media.view.MediaFrame.prototype */{
/**
* Creates the title view.
*
- * @param {Object} title
+ * @param {Object} title The title object for creating the title view.
* @this wp.media.controller.Region
*/
createTitle: function( title ) {
@@ -8141,7 +8141,7 @@ MediaFrame = Frame.extend(/** @lends wp.media.view.MediaFrame.prototype */{
/**
* Creates the menu view.
*
- * @param {Object} menu
+ * @param {Object} menu The menu object for creating the menu view.
* @this wp.media.controller.Region
*/
createMenu: function( menu ) {
@@ -8172,7 +8172,7 @@ MediaFrame = Frame.extend(/** @lends wp.media.view.MediaFrame.prototype */{
/**
* Creates the toolbar view.
*
- * @param {Object} toolbar
+ * @param {Object} toolbar The toolbar object for creating the toolbar view.
* @this wp.media.controller.Region
*/
createToolbar: function( toolbar ) {
@@ -8183,7 +8183,7 @@ MediaFrame = Frame.extend(/** @lends wp.media.view.MediaFrame.prototype */{
/**
* Creates the router view.
*
- * @param {Object} router
+ * @param {Object} router The router object for creating the router view.
* @this wp.media.controller.Region
*/
createRouter: function( router ) {
@@ -8201,7 +8201,7 @@ MediaFrame = Frame.extend(/** @lends wp.media.view.MediaFrame.prototype */{
/**
* Creates the iframe states.
*
- * @param {Object} options
+ * @param {Object} options The options for creating the iframe states.
*/
createIframeStates: function( options ) {
var settings = wp.media.view.settings,
@@ -8240,7 +8240,7 @@ MediaFrame = Frame.extend(/** @lends wp.media.view.MediaFrame.prototype */{
/**
* Creates the iframe content view.
*
- * @param {Object} content
+ * @param {Object} content The content object for creating the iframe content view.
* @this wp.media.controller.Region
*/
iframeContent: function( content ) {
@@ -8508,8 +8508,8 @@ Menu = PriorityList.extend(/** @lends wp.media.view.Menu.prototype */{
/**
* Creates a view for the given options and id.
*
- * @param {Object} options
- * @param {string} id
+ * @param {Object} options The options for creating the view.
+ * @param {string} id The id of the view to create.
* @return {wp.media.View} The view instance.
*/
toView: function( options, id ) {
@@ -8771,7 +8771,8 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
/**
* Closes the modal and triggers the close event.
*
- * @param {Object} options
+ * @param {Object} [options={}] The options for closing the modal.
+ * @param {boolean} [options.escape] Whether the modal is being closed due to the escape key.
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
close: function( options ) {
@@ -8824,7 +8825,7 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
/**
* Handles the escape key press event to close the modal.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object.
*/
escapeHandler: function( event ) {
event.preventDefault();
@@ -8836,7 +8837,7 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
*
* @since 6.7
*
- * @param {Object} event The keydown event object.
+ * @param {JQuery.Event} event The jQuery event object.
*/
selectHandler: function( event ) {
var selection = this.controller.state().get( 'selection' );
@@ -8869,7 +8870,7 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
* Triggers a modal event and if the `propagate` option is set,
* forwards events to the modal's controller.
*
- * @param {string} id
+ * @param {string} id The ID of the event to propagate.
* @return {wp.media.view.Modal} Returns itself to allow chaining.
*/
propagate: function( id ) {
@@ -8884,7 +8885,7 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
/**
* Handles keydown events within the modal.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery keydown event object.
*/
keydown: function( event ) {
// Close the modal when escape is pressed.
@@ -8936,9 +8937,9 @@ 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
+ * @param {string} id The ID of the view to set.
+ * @param {wp.media.View|Object} view The view to set.
+ * @param {Object} options The options for setting the view.
* @return {wp.media.view.PriorityList} Returns itself to allow chaining.
*/
set: function( id, view, options ) {
@@ -8981,7 +8982,7 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr
/**
* Retrieves a view by its ID.
*
- * @param {string} id
+ * @param {string} id The ID of the view to retrieve.
* @return {wp.media.View} Returns the view if found, otherwise undefined.
*/
get: function( id ) {
@@ -8990,7 +8991,7 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr
/**
* Removes a view by its ID.
*
- * @param {string} id
+ * @param {string} id The ID of the view to remove.
* @return {wp.media.view.PriorityList} Returns itself to allow chaining.
*/
unset: function( id ) {
@@ -9006,7 +9007,7 @@ var PriorityList = wp.media.View.extend(/** @lends wp.media.view.PriorityList.pr
/**
* Creates a view from an object of options.
*
- * @param {Object} options
+ * @param {Object} options The options for creating the view.
* @return {wp.media.View} Returns the created view.
*/
toView: function( options ) {
@@ -9309,7 +9310,7 @@ Settings = View.extend(/** @lends wp.media.view.Settings.prototype */{
/**
* Updates the selected value for a setting.
*
- * @param {string} key
+ * @param {string} key The key of the setting to update.
*/
update: function( key ) {
var value = this.model.get( key ),
@@ -9358,7 +9359,7 @@ Settings = View.extend(/** @lends wp.media.view.Settings.prototype */{
/**
* Updates the model when a setting is changed.
*
- * @param {Object} event
+ * @param {JQuery.Event} event The jQuery event object associated with the setting change.
*/
updateHandler: function( event ) {
var $setting = $( event.target ).closest('[data-setting]'),
@@ -9846,9 +9847,9 @@ Toolbar = View.extend(/** @lends wp.media.view.Toolbar.prototype */{
/**
* Sets a view by its ID.
*
- * @param {string} id
- * @param {Backbone.View|Object} view
- * @param {Object} [options={}]
+ * @param {string} id The ID of the view to set.
+ * @param {Backbone.View|Object} view The view to set.
+ * @param {Object} [options={}] The options for setting the view.
* @return {wp.media.view.Toolbar} Returns itself to allow chaining.
*/
set: function( id, view, options ) {
@@ -9884,7 +9885,7 @@ Toolbar = View.extend(/** @lends wp.media.view.Toolbar.prototype */{
/**
* Retrieves a view by its ID.
*
- * @param {string} id
+ * @param {string} id The ID of the view to retrieve.
* @return {wp.media.view.Button} The view associated with the given ID, or undefined if no view is found.
*/
get: function( id ) {
@@ -9893,8 +9894,8 @@ Toolbar = View.extend(/** @lends wp.media.view.Toolbar.prototype */{
/**
* Unsets a view by its ID.
*
- * @param {string} id
- * @param {Object} options
+ * @param {string} id The ID of the view to unset.
+ * @param {Object} [options={}] The options for unsetting the view.
* @return {wp.media.view.Toolbar} Returns itself to allow chaining.
*/
unset: function( id, options ) {
@@ -10600,7 +10601,7 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype *
/**
* Escapes the filename to prevent XSS attacks.
*
- * @param {string} filename
+ * @param {string} filename The name of the file to be escaped.
* @return {string} Escaped filename.
*/
filename: function( filename ) {
@@ -10609,7 +10610,7 @@ UploaderStatus = View.extend(/** @lends wp.media.view.UploaderStatus.prototype *
/**
* Handles an error event from the uploader queue.
*
- * @param {Backbone.Model} error
+ * @param {Backbone.Model} error The error model from the uploader queue.
* @return {void}
*/
error: function( error ) {
@@ -10932,8 +10933,8 @@ media.events = _.extend( {}, Backbone.Events );
/**
* Makes it easier to bind events using transitions.
*
- * @param {string} selector
- * @param {number} sensitivity
+ * @param {string} selector The CSS selector for the element to bind the transition event to.
+ * @param {number} sensitivity The maximum time to wait for the transition event before resolving the promise.
* @return {Promise} A promise that resolves when the transition has completed.
*/
media.transition = function( selector, sensitivity ) {
diff --git a/wp-includes/js/wp-api.js b/wp-includes/js/wp-api.js
index a66d96c3fb..b15a74628a 100644
--- a/wp-includes/js/wp-api.js
+++ b/wp-includes/js/wp-api.js
@@ -1546,7 +1546,7 @@
/**
* Initialize the wp-api, optionally passing the API root.
*
- * @param {Object} [args]
+ * @param {Object} [args] The arguments for initializing the wp-api.
* @param {string} [args.nonce] The nonce. Optional, defaults to wpApiSettings.nonce.
* @param {string} [args.apiRoot] The api root. Optional, defaults to wpApiSettings.root.
* @param {string} [args.versionString] The version string. Optional, defaults to wpApiSettings.root.
diff --git a/wp-includes/js/wp-embed-template.js b/wp-includes/js/wp-embed-template.js
index e43ef97b8f..85c1369322 100644
--- a/wp-includes/js/wp-embed-template.js
+++ b/wp-includes/js/wp-embed-template.js
@@ -196,7 +196,7 @@
/**
* Detect clicks to external (_top) links.
*
- * @param {MouseEvent} event
+ * @param {MouseEvent} event The click event object.
*/
function linkClickHandler( event ) {
/*
@@ -237,7 +237,7 @@
/**
* Message handler.
*
- * @param {MessageEvent} event
+ * @param {MessageEvent} event The message event object.
*/
function onMessage( event ) {
var data = event.data;
diff --git a/wp-includes/js/wp-lists.js b/wp-includes/js/wp-lists.js
index 3f667a0434..44e71a84ed 100644
--- a/wp-includes/js/wp-lists.js
+++ b/wp-includes/js/wp-lists.js
@@ -739,7 +739,7 @@ wpList = {
/**
* Registers event handlers to add, delete, and dim items.
*
- * @param {string} elementId
+ * @param {string} elementId ID of the element to process, including leading #.
*/
process: function( elementId ) {
var list = this,
@@ -812,7 +812,7 @@ wpList = {
/**
* Initializes wpList object.
*
- * @param {Object} settings
+ * @param {Object} settings The settings for the wpList instance.
* @param {string} settings.url URL for ajax calls. Default: ajaxurl.
* @param {string} settings.type The HTTP method to use for Ajax requests. Default: 'POST'.
* @param {string} settings.response ID of the element the parsed ajax response will be stored in.
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 117e923440..c865ea1e03 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-alpha-63597';
+$wp_version = '7.2-alpha-63598';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.