Merge branch 'trunk' into test/64895-change-assertions

Author: 3kori

.eslintrc-jsdoc.js

@@ -56,6 +56,7 @@ module.exports = [
 			'jsdoc/require-returns-type': 'error',
 			'jsdoc/check-syntax': 'error',
 			'jsdoc/require-description': 'error',
+			'jsdoc/require-jsdoc': 'error',
 		},
 	},
 ];

.github/workflows/reusable-phpunit-tests-v3.yml

@@ -154,7 +154,7 @@ jobs:
   phpunit-tests:
     name: ${{ ( inputs.phpunit-test-groups || inputs.coverage-report ) && format( 'PHP {0} with ', inputs.php ) || '' }} ${{ 'mariadb' == inputs.db-type && 'MariaDB' || 'MySQL' }} ${{ inputs.db-version }}${{ inputs.multisite && ' multisite' || '' }}${{ inputs.db-innovation && ' (innovation release)' || '' }}${{ inputs.memcached && ' with memcached' || '' }}${{ inputs.report && ' (test reporting enabled)' || '' }} ${{ 'example.org' != inputs.tests-domain && inputs.tests-domain || '' }}
     runs-on: ${{ vars.RUNNERS_NAME || inputs.os }}
-    timeout-minutes: ${{ inputs.coverage-report && 120 || inputs.php == '8.4' && 30 || 20 }}
+    timeout-minutes: ${{ inputs.coverage-report && 120 || 30 }}
     permissions:
       contents: read
 

.github/workflows/reusable-prepare-gutenberg.yml

@@ -106,4 +106,4 @@ jobs:
           path: gutenberg/
           if-no-files-found: error
           include-hidden-files: true
-          retention-days: 1
+          retention-days: 7

Gruntfile.js

@@ -154,7 +154,11 @@ module.exports = function(grunt) {
 		]
 	};
 
-	// Load grunt-* tasks.
+	/**
+	 * Loads the Grunt tasks for the given dependency.
+	 *
+	 * @param {string} dependency The name of the Grunt task to load.
+	 */
 	function loadGruntTasks( dependency ) {
 		var contrib = key === 'contrib' ? 'contrib-' : '';
 		grunt.loadNpmTasks( 'grunt-' + contrib + dependency );
@@ -1797,6 +1801,11 @@ module.exports = function(grunt) {
 			path.dirname( __dirname ) + '/.svn'
 		] );
 
+		/**
+		 * Searches for the first version control directory in the given set.
+		 *
+		 * @param {string[]} set Array of directory paths to check.
+		 */
 		function find( set ) {
 			var dir;
 
@@ -1809,6 +1818,9 @@ module.exports = function(grunt) {
 			}
 		}
 
+		/**
+		 * Runs all tasks.
+		 */
 		function runAllTasks() {
 			grunt.log.writeln( 'Cannot determine which files are modified as SVN and GIT are not available.' );
 			grunt.log.writeln( 'Running all tasks and all tests.' );
@@ -1824,6 +1836,11 @@ module.exports = function(grunt) {
 			done();
 		}
 
+		/**
+		 * Determines which precommit tasks to run based on modified files detected by version control.
+		 *
+		 * @param {string} type The version control type: 'git' or 'svn'.
+		 */
 		function run( type ) {
 			var command = map[ type ].split( ' ' );
 
@@ -1833,13 +1850,23 @@ module.exports = function(grunt) {
 			}, function( error, result, code ) {
 				var taskList = [];
 
-				// Callback for finding modified paths.
+				/**
+				 * Checks if the given path appears in the version control status output.
+				 *
+				 * @param {string} path The path to check.
+				 * @return {boolean} True if the path is found, false otherwise.
+				 */
 				function testPath( path ) {
 					var regex = new RegExp( ' ' + path + '$', 'm' );
 					return regex.test( result.stdout );
 				}
 
-				// Callback for finding modified files by extension.
+				/**
+				 * Checks if files with the given extension appear in the version control status output.
+				 *
+				 * @param {string} extension The file extension to check for.
+				 * @return {boolean} True if the file with the given extension is found, false otherwise.
+				 */
 				function testExtension( extension ) {
 					var regex = new RegExp( '\.' + extension + '$', 'm' );
 					return regex.test( result.stdout );

src/js/_enqueues/admin/password-toggle.js

@@ -1,10 +1,12 @@
+/**
+ * @output wp-admin/js/password-toggle.js
+ */
+
 /**
  * Adds functionality for password visibility buttons to toggle between text and password input types.
  *
  * @since 6.3.0
- * @output wp-admin/js/password-toggle.js
  */
-
 ( function () {
 	var toggleElements, status, input, icon, label, __ = wp.i18n.__;
 
@@ -15,6 +17,9 @@
 		toggle.addEventListener( 'click', togglePassword );
 	} );
 
+	/**
+	 * Toggles the password input field visibility.
+	 */
 	function togglePassword() {
 		status = this.getAttribute( 'data-toggle' );
 		input = this.parentElement.children.namedItem( 'pwd' );

src/js/_enqueues/admin/plugin-install.js

@@ -6,6 +6,11 @@
 
 /* global tb_click, tb_remove, tb_position */
 
+/**
+ * Initializes the plugin install screens.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ */
 jQuery( function( $ ) {
 
 	var tbWindow,
@@ -78,6 +83,9 @@ jQuery( function( $ ) {
 			$focusedBefore.trigger( 'focus' );
 		});
 
+	/**
+	 * Initializes the plugin details modal dialog after the iframe has fully loaded.
+	 */
 	function iframeLoaded() {
 		var $iframe = tbWindow.find( '#TB_iframeContent' );
 
@@ -109,8 +117,9 @@ jQuery( function( $ ) {
 		});
 	}
 
-	/*
-	 * Get the tabbable elements and detach/attach the keydown event.
+	/**
+	 * Gets the tabbable elements and detaches/attaches the keydown event.
+	 *
 	 * Called after the iframe has fully loaded so we have all the elements we need.
 	 * Called again each time a Tab gets clicked.
 	 * @todo Consider to implement a WordPress general utility for this and don't use jQuery UI.
@@ -133,7 +142,11 @@ jQuery( function( $ ) {
 		});
 	}
 
-	// Constrain tabbing within the plugin modal dialog.
+	/**
+	 * Constrains tabbing within the plugin modal dialog.
+	 *
+	 * @param {JQuery.Event} event The keydown event.
+	 */
 	function constrainTabbing( event ) {
 		if ( 9 !== event.which ) {
 			return;
@@ -148,11 +161,13 @@ jQuery( function( $ ) {
 		}
 	}
 
-	/*
-	 * Open the Plugin details modal. The event is delegated to get also the links
-	 * in the plugins search tab, after the Ajax search rebuilds the HTML. It's
-	 * delegated on the closest ancestor and not on the body to avoid conflicts
-	 * with other handlers, see Trac ticket #43082.
+	/**
+	 * Opens the Plugin details modal.
+	 *
+	 * The event is delegated to get also the links in the plugins search tab,
+	 * after the Ajax search rebuilds the HTML. It's delegated on the closest
+	 * ancestor and not on the body to avoid conflicts with other handlers, see
+	 * Trac ticket #43082.
 	 */
 	$( '.wrap' ).on( 'click', '.thickbox.open-plugin-details-modal', function( e ) {
 		// The `data-title` attribute is used only in the Plugin screens.

src/js/_enqueues/admin/privacy-tools.js

@@ -1,19 +1,34 @@
 /**
- * Interactions used by the User Privacy tools in WordPress.
- *
  * @output wp-admin/js/privacy-tools.js
  */
 
-// Privacy request action handling.
+/**
+ * Sets the interactions used by the User Privacy tools in WordPress.
+ *
+ * @param {jQueryStatic} $ The jQuery object.
+ */
 jQuery( function( $ ) {
 	var __ = wp.i18n.__,
 		copiedNoticeTimeout;
 
+	/**
+	 * Sets the state of the action.
+	 *
+	 * @param {jQuery} $action The action to set the state for.
+	 * @param {string} state   The state to set the action to.
+	 * @return {void}
+	 */
 	function setActionState( $action, state ) {
 		$action.children().addClass( 'hidden' );
 		$action.children( '.' + state ).removeClass( 'hidden' );
 	}
 
+	/**
+	 * Clears any results row after the request row.
+	 *
+	 * @param {jQuery} $requestRow The request row to clear results for.
+	 * @return {void}
+	 */
 	function clearResultsAfterRow( $requestRow ) {
 		$requestRow.removeClass( 'has-request-results' );
 
@@ -22,6 +37,15 @@ jQuery( function( $ ) {
 		}
 	}
 
+	/**
+	 * Appends a results row after the request row.
+	 *
+	 * @param {jQuery}   $requestRow        The request row to append the results after.
+	 * @param {string}   classes            The classes to add to the results row.
+	 * @param {string}   summaryMessage     The summary message to display in the results row.
+	 * @param {string[]} additionalMessages Additional messages to display in the results row.
+	 * @return {void}
+	 */
 	function appendResultsAfterRow( $requestRow, classes, summaryMessage, additionalMessages ) {
 		var itemList = '',
 			resultRowClasses = 'request-results';
@@ -76,6 +100,12 @@ jQuery( function( $ ) {
 		clearResultsAfterRow( $requestRow );
 		setExportProgress( 0 );
 
+		/**
+		 * Handles a successful export.
+		 *
+		 * @param {string} zipUrl The URL of the generated ZIP file, if available.
+		 * @return {void}
+		 */
 		function onExportDoneSuccess( zipUrl ) {
 			var summaryMessage = __( 'This user’s personal data export link was sent.' );
 
@@ -96,6 +126,12 @@ jQuery( function( $ ) {
 			setTimeout( function() { $rowActions.removeClass( 'processing' ); }, 500 );
 		}
 
+		/**
+		 * Handles an export failure.
+		 *
+		 * @param {string} errorMessage The error message to display.
+		 * @return {void}
+		 */
 		function onExportFailure( errorMessage ) {
 			var summaryMessage = __( 'An error occurred while attempting to export personal data.' );
 
@@ -108,13 +144,26 @@ jQuery( function( $ ) {
 			setTimeout( function() { $rowActions.removeClass( 'processing' ); }, 500 );
 		}
 
+		/**
+		 * Updates the progress of the export process.
+		 *
+		 * @param {number} exporterIndex The index of the exporter to process.
+		 * @return {void}
+		 */
 		function setExportProgress( exporterIndex ) {
 			var progress       = ( exportersCount > 0 ? exporterIndex / exportersCount : 0 ),
 				progressString = Math.round( progress * 100 ).toString() + '%';
 
 			$progress.html( progressString );
 		}
 
+		/**
+		 * Performs the next export request.
+		 *
+		 * @param {number} exporterIndex The index of the exporter to process.
+		 * @param {number} pageIndex     The index of the page to process for the current exporter.
+		 * @return {void}
+		 */
 		function doNextExport( exporterIndex, pageIndex ) {
 			$.ajax(
 				{
@@ -181,6 +230,11 @@ jQuery( function( $ ) {
 		clearResultsAfterRow( $requestRow );
 		setErasureProgress( 0 );
 
+		/**
+		 * Handles a successful erasure.
+		 *
+		 * @return {void}
+		 */
 		function onErasureDoneSuccess() {
 			var summaryMessage = __( 'No personal data was found for this user.' ),
 				classes = 'notice-success';
@@ -207,6 +261,9 @@ jQuery( function( $ ) {
 			setTimeout( function() { $rowActions.removeClass( 'processing' ); }, 500 );
 		}
 
+		/**
+		 * Handles an erasure failure.
+		 */
 		function onErasureFailure() {
 			var summaryMessage = __( 'An error occurred while attempting to find and erase personal data.' );
 
@@ -217,13 +274,26 @@ jQuery( function( $ ) {
 			setTimeout( function() { $rowActions.removeClass( 'processing' ); }, 500 );
 		}
 
+		/**
+		 * Updates the progress of the erasure process.
+		 *
+		 * @param {number} eraserIndex The index of the eraser to process.
+		 * @return {void}
+		 */
 		function setErasureProgress( eraserIndex ) {
 			var progress       = ( erasersCount > 0 ? eraserIndex / erasersCount : 0 ),
 				progressString = Math.round( progress * 100 ).toString() + '%';
 
 			$progress.html( progressString );
 		}
 
+		/**
+		 * Performs the next erasure request.
+		 *
+		 * @param {number} eraserIndex The index of the eraser to process.
+		 * @param {number} pageIndex   The index of the page to process for the current eraser.
+		 * @return {void}
+		 */
 		function doNextErasure( eraserIndex, pageIndex ) {
 			$.ajax({
 				url: window.ajaxurl,

src/js/_enqueues/admin/site-health.js

@@ -1,11 +1,14 @@
 /**
- * Interactions used by the Site Health modules in WordPress.
- *
  * @output wp-admin/js/site-health.js
  */
 
 /* global ajaxurl, ClipboardJS, SiteHealth, wp */
 
+/**
+ * Handles the interactions used by the Site Health modules in WordPress.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ */
 jQuery( function( $ ) {
 
 	var __ = wp.i18n.__,
@@ -393,6 +396,9 @@ jQuery( function( $ ) {
 		}
 	}
 
+	/**
+	 * Get the sizes of the directories in the Site Health Info section.
+	 */
 	function getDirectorySizes() {
 		var timestamp = ( new Date().getTime() );
 
@@ -434,6 +440,11 @@ jQuery( function( $ ) {
 		} );
 	}
 
+	/**
+	 * Updates the directory sizes in the Site Health Info section.
+	 *
+	 * @param {Object} data The directory sizes data.
+	 */
 	function updateDirSizes( data ) {
 		var copyButton = $( 'button.button.copy-button' );
 		var clipboardText = copyButton.attr( 'data-clipboard-text' );