Jsdoc: add require param description rule

.eslintrc-jsdoc.js

@@ -52,6 +52,7 @@ module.exports = [
 			'jsdoc/require-param': [ 'error', {
 				enableFixer: false,
 			} ],
+			'jsdoc/require-param-description': 'error',
 			'jsdoc/require-param-name': 'error',
 			'jsdoc/require-param-type': 'error',
 			'jsdoc/require-returns': 'error',

src/js/_enqueues/admin/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) {

src/js/_enqueues/admin/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 ) {

src/js/_enqueues/lib/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;

src/js/_enqueues/lib/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.

src/js/_enqueues/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.

src/js/_enqueues/wp/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.
 		 */

src/js/_enqueues/wp/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 ) {

src/js/_enqueues/wp/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
 		 *

src/js/_enqueues/wp/media/models.js

@@ -136,7 +136,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 ) {
@@ -182,9 +186,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 ) {
@@ -228,7 +232,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 ) {

src/js/_enqueues/wp/media/views.js

@@ -47,8 +47,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 ) {

src/js/_enqueues/wp/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

src/js/media/controllers/embed.js

@@ -89,7 +89,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,

src/js/media/controllers/library.js

@@ -158,7 +158,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 ) {
@@ -175,7 +175,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 ) {
@@ -196,7 +196,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 ) {
@@ -213,7 +213,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 ) {
@@ -262,7 +262,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;

src/js/media/controllers/region.js

@@ -33,7 +33,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
@@ -72,7 +72,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
@@ -131,8 +131,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 ) {
@@ -147,7 +147,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 ) {

src/js/media/controllers/state-machine.js

@@ -35,7 +35,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.
 	 */
@@ -60,7 +60,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

src/js/media/models/attachment.js

@@ -14,9 +14,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.
 	 */
@@ -144,7 +144,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 ) {
@@ -158,8 +158,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 ) {