Commit b74c8833f5 for wordpress.org
commit b74c8833f567a77c9b62ed5a5e20c660036ca838
Author: afercia <afercia@git.wordpress.org>
Date: Wed Sep 9 12:03:53 2026 +0000
General: Add missing JS docblocks.
Also, enables the JSDoc rule `jsdoc/require-jsdoc`.
Part of the effort to improve JS inline documentation for 7.2.
Developed in https://github.com/WordPress/wordpress-develop/pull/13439
Props afercia, westonruter.
See #66033.
Built from https://develop.svn.wordpress.org/trunk@63556
git-svn-id: http://core.svn.wordpress.org/trunk@62732 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-admin/js/customize-controls.js b/wp-admin/js/customize-controls.js
index 2a1818b8bb..94693163c0 100644
--- a/wp-admin/js/customize-controls.js
+++ b/wp-admin/js/customize-controls.js
@@ -843,6 +843,9 @@
options
);
+ /**
+ * Cancels the reminder, preventing the button from being highlighted.
+ */
function cancelReminder() {
canceled = true;
}
@@ -1981,6 +1984,9 @@
api.section( 'wporg_themes' ).focus();
});
+ /**
+ * Updates the section header to reflect the expanded state.
+ */
function updateSelectedState() {
var el = section.headerContainer.find( '.customize-themes-section-title' );
el.toggleClass( 'selected', section.expanded() );
@@ -2025,6 +2031,9 @@
return;
}
+ /**
+ * Expands the section.
+ */
function expand() {
// Try to load controls if none are loaded yet.
@@ -2625,11 +2634,21 @@
.fadeIn( 'fast' )
.focus();
+ /**
+ * Disables the switch buttons if the theme cannot be switched to.
+ *
+ * @return {boolean} True if the switch buttons should be disabled, false otherwise.
+ */
function disableSwitchButtons() {
return ! panel.canSwitchTheme( theme.id );
}
// Temporary special function since supplying SFTP credentials does not work yet. See #42184.
+ /**
+ * Disables the install buttons if the theme cannot be installed or if filesystem credentials are needed.
+ *
+ * @return {boolean} True if the install buttons should be disabled, false otherwise.
+ */
function disableInstallButtons() {
return disableSwitchButtons() || false === api.settings.theme._canInstall || true === api.settings.theme._filesystemCredentialsNeeded;
}
@@ -3137,6 +3156,9 @@
} ) );
}
+ /**
+ * Toggles the theme switch unavailable notification based on whether switching is possible.
+ */
function toggleDisabledNotifications() {
if ( panel.canSwitchTheme() ) {
panel.notifications.remove( 'theme_switch_unavailable' );
@@ -5215,14 +5237,28 @@
ready: function() {
var control = this, panel = api.panel( 'themes' );
+ /**
+ * Disables the preview buttons if the theme cannot be switched to.
+ *
+ * @return {boolean} True if the preview buttons should be disabled, false otherwise.
+ */
function disableSwitchButtons() {
return ! panel.canSwitchTheme( control.params.theme.id );
}
// Temporary special function since supplying SFTP credentials does not work yet. See #42184.
+ /**
+ * Disables the install buttons if the theme cannot be installed or if filesystem credentials are needed.
+ *
+ * @return {boolean} True if the install buttons should be disabled, false otherwise.
+ */
function disableInstallButtons() {
return disableSwitchButtons() || false === api.settings.theme._canInstall || true === api.settings.theme._filesystemCredentialsNeeded;
}
+
+ /**
+ * Updates the state of the preview and install buttons based on whether the theme can be switched to or installed.
+ */
function updateButtons() {
control.container.find( 'button.preview, button.preview-theme' ).toggleClass( 'disabled', disableSwitchButtons() );
control.container.find( 'button.theme-install' ).toggleClass( 'disabled', disableInstallButtons() );
@@ -7336,6 +7372,9 @@
updateButtonsState();
section.active.bind( updateButtonsState );
+ /**
+ * Highlights the schedule button to remind the user to schedule the changes.
+ */
function highlightScheduleButton() {
if ( ! cancelScheduleButtonReminder ) {
cancelScheduleButtonReminder = api.utils.highlightButton( btnWrapper, {
@@ -7350,6 +7389,10 @@
} );
}
}
+
+ /**
+ * Cancels the highlight reminder for the schedule button.
+ */
function cancelHighlightScheduleButton() {
if ( cancelScheduleButtonReminder ) {
cancelScheduleButtonReminder();
@@ -7591,6 +7634,11 @@
api.state( 'saving' ).set( true );
+ /**
+ * Captures a setting as modified during the save process.
+ *
+ * @param {wp.customize.Setting} setting The setting that was modified.
+ */
function captureSettingModifiedDuringSave( setting ) {
modifiedWhileSaving[ setting.id ] = true;
}
@@ -8933,6 +8981,11 @@
(function() {
var isInsideIframe = false;
+ /**
+ * Determine whether the Customizer is in a clean state.
+ *
+ * @return {boolean} True if the Customizer is in a clean state, false otherwise.
+ */
function isCleanState() {
var defaultChangesetStatus;
@@ -8969,6 +9022,9 @@
isInsideIframe = true;
});
+ /**
+ * Starts prompting the user before unloading the Customizer if there are unsaved changes.
+ */
function startPromptingBeforeUnload() {
api.unbind( 'change', startPromptingBeforeUnload );
api.state( 'selectedChangesetStatus' ).unbind( startPromptingBeforeUnload );
@@ -8988,6 +9044,11 @@
api.state( 'selectedChangesetStatus' ).bind( startPromptingBeforeUnload );
api.state( 'selectedChangesetDate' ).bind( startPromptingBeforeUnload );
+ /**
+ * Requests to close the Customizer, prompting the user to save changes if necessary.
+ *
+ * @return {JQuery.Promise} A promise that resolves if the user is cleared to close the Customizer, or rejects if the user cancels the close.
+ */
function requestClose() {
var clearedToClose = $.Deferred(), dismissAutoSave = false, dismissLock = false;
@@ -9377,12 +9438,19 @@
api.previewer.send( 'edit-shortcut-visibility', visibility );
} );
- // Autosave changeset.
+ /**
+ * Starts autosaving changeset when a change is made.
+ */
function startAutosaving() {
var timeoutId, updateChangesetWithReschedule, scheduleChangesetUpdate, updatePending = false;
api.unbind( 'change', startAutosaving ); // Ensure startAutosaving only fires once.
+ /**
+ * Handles changes to the saved state of the changeset.
+ *
+ * @param {boolean} isSaved Whether the changeset is saved or not.
+ */
function onChangeSaved( isSaved ) {
if ( ! isSaved && ! api.settings.changeset.autosaved ) {
api.settings.changeset.autosaved = true; // Once a change is made then autosaving kicks in.
diff --git a/wp-admin/js/customize-widgets.js b/wp-admin/js/customize-widgets.js
index 5f8faf2970..5af1e8007d 100644
--- a/wp-admin/js/customize-widgets.js
+++ b/wp-admin/js/customize-widgets.js
@@ -2358,6 +2358,11 @@
*/
function focusConstructWithBreadcrumb( focusConstruct, returnConstruct ) {
focusConstruct.focus();
+ /**
+ * Determines whether to return focus to the returnConstruct after the focusConstruct is collapsed.
+ *
+ * @param {boolean} isExpanded Whether the focusConstruct is expanded.
+ */
function onceCollapsed( isExpanded ) {
if ( ! isExpanded ) {
focusConstruct.expanded.unbind( onceCollapsed );
diff --git a/wp-admin/js/editor-expand.js b/wp-admin/js/editor-expand.js
index 3e5276ed3e..d6a563e8f7 100644
--- a/wp-admin/js/editor-expand.js
+++ b/wp-admin/js/editor-expand.js
@@ -1360,6 +1360,12 @@
setTimeout( function() {
var position = document.activeElement.compareDocumentPosition( $editor.get( 0 ) );
+ /**
+ * Determines whether the passed element has focus.
+ *
+ * @param {jQuery} $el The element to check for focus.
+ * @return {boolean} True if the element has focus, false otherwise.
+ */
function hasFocus( $el ) {
return $.contains( $el.get( 0 ), document.activeElement );
}
@@ -1524,10 +1530,16 @@
$document.on( 'tinymce-editor-init.focus', function( event, editor ) {
var mceBind, mceUnbind;
+ /**
+ * Tracks when the TinyMCE editor receives focus.
+ */
function focus() {
editorHasFocus = true;
}
+ /**
+ * Tracks when the TinyMCE editor loses focus.
+ */
function blur() {
editorHasFocus = false;
}
diff --git a/wp-admin/js/editor.js b/wp-admin/js/editor.js
index c2c264e3f8..0c3485ca7d 100644
--- a/wp-admin/js/editor.js
+++ b/wp-admin/js/editor.js
@@ -4,6 +4,12 @@
window.wp = window.wp || {};
+/**
+ * The editor functionality.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Object} wp The WordPress global object.
+ */
( function( $, wp ) {
wp.editor = wp.editor || {};
@@ -17,6 +23,9 @@ window.wp = window.wp || {};
var tinymce, $$,
exports = {};
+ /**
+ * Initializes the editor utility functions.
+ */
function init() {
if ( ! tinymce && window.tinymce ) {
tinymce = window.tinymce;
diff --git a/wp-admin/js/nav-menu.js b/wp-admin/js/nav-menu.js
index f70ca7c99f..5e94a2b34f 100644
--- a/wp-admin/js/nav-menu.js
+++ b/wp-admin/js/nav-menu.js
@@ -1013,6 +1013,11 @@
}
});
+ /**
+ * Updates the shared variables used to determine the depth of the menu item being moved.
+ *
+ * @param {Object} ui The jQuery UI object for the menu item being moved.
+ */
function updateSharedVars(ui) {
var depth;
@@ -1033,17 +1038,35 @@
maxDepth = 0;
}
+ /**
+ * Updates the current depth of the menu item being moved.
+ *
+ * @param {Object} ui The jQuery UI object for the menu item being moved.
+ * @param {number} depth The new depth of the menu item being moved.
+ * @return {void}
+ */
function updateCurrentDepth(ui, depth) {
ui.placeholder.updateDepthClass( depth, currentDepth );
currentDepth = depth;
}
+ /**
+ * Determines the initial menu max depth class on the body element.
+ *
+ * @return {number} The initial menu max depth.
+ */
function initialMenuMaxDepth() {
if( ! body[0].className ) return 0;
var match = body[0].className.match(/menu-max-depth-(\d+)/);
return match && match[1] ? parseInt( match[1], 10 ) : 0;
}
+ /**
+ * Updates the menu max depth class on the body element.
+ *
+ * @param {number} depthChange The change in depth of the menu item being moved.
+ * @return {void}
+ */
function updateMenuMaxDepth( depthChange ) {
var depth, newDepth = menuMaxDepth;
if ( depthChange === 0 ) {
diff --git a/wp-admin/js/password-toggle.js b/wp-admin/js/password-toggle.js
index 5bfaa3b122..bdd98f8bb7 100644
--- a/wp-admin/js/password-toggle.js
+++ b/wp-admin/js/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' );
diff --git a/wp-admin/js/plugin-install.js b/wp-admin/js/plugin-install.js
index 1e994763e1..b79931a7e7 100644
--- a/wp-admin/js/plugin-install.js
+++ b/wp-admin/js/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.
diff --git a/wp-admin/js/privacy-tools.js b/wp-admin/js/privacy-tools.js
index 480766ad05..df24538ffa 100644
--- a/wp-admin/js/privacy-tools.js
+++ b/wp-admin/js/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,6 +144,12 @@ 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() + '%';
@@ -115,6 +157,13 @@ jQuery( function( $ ) {
$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,6 +274,12 @@ 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() + '%';
@@ -224,6 +287,13 @@ jQuery( function( $ ) {
$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,
diff --git a/wp-admin/js/site-health.js b/wp-admin/js/site-health.js
index 98aaedc427..dc9107a3eb 100644
--- a/wp-admin/js/site-health.js
+++ b/wp-admin/js/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' );
diff --git a/wp-admin/js/tags-suggest.js b/wp-admin/js/tags-suggest.js
index 08bea1464b..e7469cfea2 100644
--- a/wp-admin/js/tags-suggest.js
+++ b/wp-admin/js/tags-suggest.js
@@ -1,7 +1,9 @@
/**
- * Default settings for jQuery UI Autocomplete for use with non-hierarchical taxonomies.
- *
* @output wp-admin/js/tags-suggest.js
+ */
+
+/**
+ * Default settings for jQuery UI Autocomplete for use with non-hierarchical taxonomies.
*
* @param {JQueryStatic} $ The jQuery object.
*/
@@ -12,16 +14,28 @@
_n = wp.i18n._n,
sprintf = wp.i18n.sprintf;
+ /**
+ * Splits a string into an array of terms based on the separator.
+ *
+ * @param {string} val The string to split.
+ * @return {string[]} An array of terms.
+ */
function split( val ) {
return val.split( new RegExp( separator + '\\s*' ) );
}
+ /**
+ * Gets the last term from a string based on the separator.
+ *
+ * @param {string} term The string to get the last term from.
+ * @return {string} The last term.
+ */
function getLast( term ) {
return split( term ).pop();
}
/**
- * Add UI Autocomplete to an input or textarea element with presets for use
+ * Adds UI Autocomplete to an input or textarea element with presets for use
* with non-hierarchical taxonomies.
*
* Example: `$( element ).wpTagsSuggest( options )`.
diff --git a/wp-admin/js/theme-plugin-editor.js b/wp-admin/js/theme-plugin-editor.js
index 88c985be42..74e0634f94 100644
--- a/wp-admin/js/theme-plugin-editor.js
+++ b/wp-admin/js/theme-plugin-editor.js
@@ -418,6 +418,9 @@ wp.themePluginEditor = (function( $ ) {
editor = wp.codeEditor.initialize( $( '#newcontent' ), codeEditorSettings );
editor.codemirror.on( 'change', component.onChange );
+ /**
+ * Handles the save shortcut (Ctrl+S / Cmd+S).
+ */
function onSaveShortcut() {
component.form.trigger( 'submit' );
}
@@ -601,10 +604,22 @@ wp.themePluginEditor = (function( $ ) {
var flag = false,
_char = event.key;
+ /**
+ * Determines whether a character is a printable character.
+ *
+ * @param {string} str The character to check.
+ * @return {boolean} True if the character is printable, false otherwise.
+ */
function isPrintableCharacter(str) {
return str.length === 1 && str.match(/\S/);
}
+ /**
+ * Handles printable character key press.
+ *
+ * @param {TreeitemLink} item The tree item link instance.
+ * @return {void}
+ */
function printableCharacter(item) {
if (_char == '*') {
item.tree.expandAllSiblingItems(item);
@@ -808,7 +823,14 @@ wp.themePluginEditor = (function( $ ) {
};
TreeLinks.prototype.init = function () {
-
+ /**
+ * Finds all treeitems and groups and creates object instances.
+ *
+ * @param {Element} node The DOM node to search for treeitems.
+ * @param {TreeLinks} tree The TreeLinks instance.
+ * @param {TreeitemLink|boolean} group The parent TreeitemLink instance or false if there is no parent.
+ * @return {void}
+ */
function findTreeitems(node, tree, group) {
var elem = node.firstElementChild;
diff --git a/wp-admin/js/user-profile.js b/wp-admin/js/user-profile.js
index e6b79f616f..dc0b5e8ccd 100644
--- a/wp-admin/js/user-profile.js
+++ b/wp-admin/js/user-profile.js
@@ -32,6 +32,17 @@
isSafari = window.safari !== 'undefined' && typeof window.safari === 'object',
isFirefox = ua.indexOf( 'firefox' ) !== -1;
+ /**
+ * Generates a password and updates the password input field.
+ *
+ * If zxcvbn is not yet loaded, it will wait and try again. If the password
+ * input field is empty or the password wrapper is open, it will set the
+ * password to the generated value. If the user has already entered a
+ * password, it will check the strength of that password. It also binds
+ * the toggle button to show or hide the password and sets the initial state
+ * of the toggle button based on whether the password should be masked or
+ * not. Finally, it updates the label for confirming weak passwords.
+ */
function generatePassword() {
if ( typeof zxcvbn !== 'function' ) {
setTimeout( generatePassword, 50 );
@@ -67,6 +78,9 @@
$( '#pw-weak-text-label' ).text( __( 'Confirm use of weak password' ) );
}
+ /**
+ * Binds the password input field to update the current password and refresh the password strength area when the user types in the field.
+ */
function bindPass1() {
currentPass = $pass1.val();
@@ -89,6 +103,11 @@
bindCapsLockWarning( $pass1 );
}
+ /**
+ * Resets the toggle button to show or hide the password.
+ *
+ * @param {boolean} show Whether to show the password or not.
+ */
function resetToggle( show ) {
$toggleButton
.attr({
@@ -102,6 +121,9 @@
.addClass( show ? 'dashicons-visibility' : 'dashicons-hidden' );
}
+ /**
+ * Binds the toggle button to show or hide the password. Also ensures that the password input type is set to password when the form is submitted.
+ */
function bindToggleButton() {
if ( !! $toggleButton ) {
// Do not rebind.
@@ -193,6 +215,9 @@
$this.before( resultDiv );
}
+ /**
+ * Initializes the password form, including the password strength meter, weak password checkbox, and show/hide password toggle button.
+ */
function bindPasswordForm() {
var $generateButton,
$cancelButton;
@@ -309,6 +334,9 @@
});
}
+ /**
+ * Sets CSS classes to the password strength results based on the password strength.
+ */
function check_pass_strength() {
var pass1 = $('#pass1').val(), strength;
@@ -414,6 +442,9 @@
return event.getModifierState( 'CapsLock' );
}
+ /**
+ * Toggles the visibility of the weak password checkbox.
+ */
function showOrHideWeakPasswordCheckbox() {
var passStrengthResult = $('#pass-strength-result');
diff --git a/wp-includes/js/api-request.js b/wp-includes/js/api-request.js
index a72fd08b37..4762a37f65 100644
--- a/wp-includes/js/api-request.js
+++ b/wp-includes/js/api-request.js
@@ -21,11 +21,38 @@
( function( $ ) {
var wpApiSettings = window.wpApiSettings;
+ /**
+ * Makes an API request.
+ *
+ * @param {Object} options The options for the API request.
+ * @param {string} [options.url] The full URL for the request.
+ * @param {string} [options.path] The API path (e.g., 'wp/v2/posts'). Used if url is not provided.
+ * @param {string} [options.namespace] The API namespace (e.g., 'wp/v2'). Used with endpoint to build path.
+ * @param {string} [options.endpoint] The API endpoint (e.g., 'posts'). Used with namespace to build path.
+ * @param {string} [options.method] The HTTP method (GET, POST, PUT, DELETE, etc.).
+ * @param {Object} [options.data] The request data to send.
+ * @param {string} [options.data._wpnonce] Nonce for security.
+ * @param {Object} [options.headers] Custom headers to include in the request.
+ * @return {JQueryXHR} The jQuery XHR object.
+ */
function apiRequest( options ) {
options = apiRequest.buildAjaxOptions( options );
return apiRequest.transport( options );
}
+ /**
+ * Builds the options for the jQuery.ajax request.
+ *
+ * @param {Object} options The options for the API request.
+ * @param {string} [options.url] The full URL for the request.
+ * @param {string} [options.path] The API path (e.g., 'wp/v2/posts'). Used if url is not provided.
+ * @param {string} [options.namespace] The API namespace (e.g., 'wp/v2'). Used with endpoint to build path.
+ * @param {string} [options.endpoint] The API endpoint (e.g., 'posts'). Used with namespace to build path.
+ * @param {string} [options.method] The HTTP method (GET, POST, PUT, DELETE, etc.).
+ * @param {Object} [options.data] The request data to send.
+ * @param {Object} [options.headers] Custom headers to include in the request.
+ * @return {Object} The options for the jQuery.ajax request.
+ */
apiRequest.buildAjaxOptions = function( options ) {
var url = options.url;
var path = options.path;
diff --git a/wp-includes/js/autosave.js b/wp-includes/js/autosave.js
index 35d7a055ed..4ad4e7fe56 100644
--- a/wp-includes/js/autosave.js
+++ b/wp-includes/js/autosave.js
@@ -449,6 +449,12 @@ window.autosave = function() {
* @return {boolean} True if the strings are the same.
*/
function compare( str1, str2 ) {
+ /**
+ * Removes all whitespace characters from a string.
+ *
+ * @param {string} string The string to remove whitespace from.
+ * @return {string} The string without whitespace characters.
+ */
function removeSpaces( string ) {
return string.toString().replace(/[\x20\t\r\n\f]+/g, '');
}
diff --git a/wp-includes/js/mce-view.js b/wp-includes/js/mce-view.js
index 01dbaedf1f..4bbd71efc3 100644
--- a/wp-includes/js/mce-view.js
+++ b/wp-includes/js/mce-view.js
@@ -4,7 +4,7 @@
/* global tinymce */
-/*
+/**
* The TinyMCE view API.
*
* Note: this API is "experimental" meaning that it will probably change
@@ -25,6 +25,11 @@
* | | |- ...
* |- registered view
* | |- ...
+ *
+ * @param {Window} window The global window object.
+ * @param {Object} wp The WordPress global object.
+ * @param {Object} shortcode The shortcode API.
+ * @param {JQueryStatic} $ The jQuery object.
*/
( function( window, wp, shortcode, $ ) {
'use strict';
@@ -615,6 +620,9 @@
iframeDoc.close();
+ /**
+ * Resizes the iframe to fit its content.
+ */
function resize() {
var $iframe;
@@ -643,6 +651,9 @@
}, 3000 );
}
+ /**
+ * Adds a MutationObserver to the iframe's body to watch for changes and resize accordingly.
+ */
function addObserver() {
observer = new MutationObserver( _.debounce( resize, 100 ) );
@@ -763,15 +774,27 @@
} );
} )( window, window.wp, window.wp.shortcode, window.jQuery );
-/*
+/**
* The WordPress core TinyMCE views.
+ *
* Views for the gallery, audio, video, playlist and embed shortcodes,
* and a view for embeddable URLs.
+ *
+ * @param {Window} window The global window object.
+ * @param {Object} views The wp.mce.views object.
+ * @param {Object} media The wp.media object.
+ * @param {JQueryStatic} $ The jQuery object.
*/
( function( window, views, media, $ ) {
var base, gallery, av, embed,
schema, parser, serializer;
+ /**
+ * Verifies that a given string is valid HTML.
+ *
+ * @param {string} string The string to verify.
+ * @return {string} The verified string.
+ */
function verifyHTML( string ) {
var settings = {};
diff --git a/wp-includes/js/quicktags.js b/wp-includes/js/quicktags.js
index 621fab1058..bdb978750e 100644
--- a/wp-includes/js/quicktags.js
+++ b/wp-includes/js/quicktags.js
@@ -233,6 +233,12 @@ window.edToolbar = function(){};
t.init();
};
+ /**
+ * Escapes HTML special characters in a string.
+ *
+ * @param {string} text The string to escape.
+ * @return {string} The escaped string.
+ */
function _escape( text ) {
text = text || '';
text = text.replace( /&([^#])(?![a-z1-4]{1,8};)/gi, '&$1' );
@@ -248,6 +254,11 @@ window.edToolbar = function(){};
qt._buttonsInit = function( id ) {
var t = this;
+ /**
+ * Initializes the Quicktags buttons for a specific instance.
+ *
+ * @param {string} instanceId The ID of the Quicktags instance to initialize buttons for.
+ */
function _init( instanceId ) {
var canvas, name, settings, theButtons, html, ed, id, i, use,
defaults = ',strong,em,link,block,del,ins,img,ul,ol,li,code,more,close,';
diff --git a/wp-includes/js/wp-custom-header.js b/wp-includes/js/wp-custom-header.js
index 1771ce7505..7d4fa98d7c 100644
--- a/wp-includes/js/wp-custom-header.js
+++ b/wp-includes/js/wp-custom-header.js
@@ -244,6 +244,11 @@
BaseHandler.extend = function( protoProps ) {
var prop;
+ /**
+ * Creates a custom handler instance.
+ *
+ * @return {CustomHandler} A custom handler instance, when called with new.
+ */
function CustomHandler() {
var result = BaseHandler.apply( this, arguments );
return result;
diff --git a/wp-includes/js/wp-embed-template.js b/wp-includes/js/wp-embed-template.js
index b053be7cc8..e43ef97b8f 100644
--- a/wp-includes/js/wp-embed-template.js
+++ b/wp-includes/js/wp-embed-template.js
@@ -5,8 +5,8 @@
/**
* IIFE setup function.
*
- * @param {Window} window Global window object.
- * @param {Document} document Global document object.
+ * @param {Window} window The global window object.
+ * @param {Document} document The global document object.
*/
(function ( window, document ) {
'use strict';
@@ -17,6 +17,12 @@
secretTimeout,
resizing;
+ /**
+ * Sends a message to the parent window.
+ *
+ * @param {string} message The message type (e.g., 'height', 'link').
+ * @param {*} value The message value. Type depends on message (number for height, string for link).
+ */
function sendEmbedMessage( message, value ) {
window.parent.postMessage( {
message: message,
diff --git a/wp-includes/js/wp-embed.js b/wp-includes/js/wp-embed.js
index 724daa3283..5522fb824a 100644
--- a/wp-includes/js/wp-embed.js
+++ b/wp-includes/js/wp-embed.js
@@ -87,6 +87,9 @@
}
};
+ /**
+ * Initializes the embed script on DOMContentLoaded.
+ */
function onLoad() {
var iframes = document.querySelectorAll( 'iframe.wp-embedded-content' ),
i, source, secret;
diff --git a/wp-includes/js/wplink.js b/wp-includes/js/wplink.js
index a2500a9069..0d1a5a923e 100644
--- a/wp-includes/js/wplink.js
+++ b/wp-includes/js/wplink.js
@@ -2,8 +2,15 @@
* @output wp-includes/js/wplink.js
*/
- /* global wpLink */
+/* global wpLink */
+/**
+ * The WordPress Link Modal dialog.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {Object} wpLinkL10n The WordPress Link localization object.
+ * @param {Object} wp The WordPress global object.
+ */
( function( $, wpLinkL10n, wp ) {
var editor, searchTimer, River, Query, correctedURL,
emailRegexp = /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,63}$/i,
@@ -12,6 +19,11 @@
rivers = {},
isTouch = ( 'ontouchend' in document );
+ /**
+ * Gets the currently selected link in the editor.
+ *
+ * @return {JQuery} The currently selected link element.
+ */
function getLink() {
if ( editor ) {
return editor.$( 'a[data-wplink-edit="true"]' );
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 9de7411468..1751ead550 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-alpha-63554';
+$wp_version = '7.2-alpha-63556';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.