Commit 77d251c4a0 for wordpress.org
commit 77d251c4a0533edb0650a318e073c427ace39d40
Author: afercia <afercia@git.wordpress.org>
Date: Mon Sep 7 11:45:51 2026 +0000
General: Add missing descriptions to several JS docblocks in the enqueues directory.
Part of the effort to improve JS inline documentation for WordPress 7.2. Preparation for the introduction of the JSDoc rule `jsdoc/require-description`.
Developed in https://github.com/WordPress/wordpress-develop/pull/13421
See #66033.
Built from https://develop.svn.wordpress.org/trunk@63514
git-svn-id: http://core.svn.wordpress.org/trunk@62690 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-admin/js/accordion.js b/wp-admin/js/accordion.js
index 12daff74a0..867b6d7ac0 100644
--- a/wp-admin/js/accordion.js
+++ b/wp-admin/js/accordion.js
@@ -30,6 +30,8 @@
*/
/**
+ * Handles the accordion functionality.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ){
diff --git a/wp-admin/js/application-passwords.js b/wp-admin/js/application-passwords.js
index 2e6f2e82c1..ab3d2fc4de 100644
--- a/wp-admin/js/application-passwords.js
+++ b/wp-admin/js/application-passwords.js
@@ -3,6 +3,8 @@
*/
/**
+ * Handles the Application Passwords functionality in the user profile screen.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
diff --git a/wp-admin/js/code-editor.js b/wp-admin/js/code-editor.js
index 74276d6438..a40a943fed 100644
--- a/wp-admin/js/code-editor.js
+++ b/wp-admin/js/code-editor.js
@@ -138,11 +138,10 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
*/
/**
- * @param {JQueryStatic} $ The jQuery object.
- * @param {Object & {
- * codeEditor: WpCodeEditor,
- * CodeMirror: typeof import('codemirror'),
- * }} wp - WordPress namespace.
+ * Handles the Code Editor (CodeMirror) functionality.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {wp} wp The WordPress global object.
*/
( function( $, wp ) {
'use strict';
@@ -165,7 +164,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
};
/**
- * Configure linting.
+ * Configures linting.
*
* @param {CodeEditorSettings} settings - Code editor settings.
*
@@ -192,7 +191,7 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
}
/**
- * Get lint options.
+ * Gets the lint options.
*
* @return {CombinedLintOptions|false} Lint options.
*/
@@ -236,6 +235,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
// Wrap the onUpdateLinting CodeMirror event to route to onChangeLintingErrors and onUpdateErrorNotice.
linterOptions.onUpdateLinting = (function( onUpdateLintingOverridden ) {
/**
+ * Wraps the onUpdateLinting event to filter errors, detect state changes, and manage error notice visibility.
+ *
* @param {LintAnnotation[]} annotations - Annotations.
* @param {LintAnnotation[]} annotationsSorted - Sorted annotations.
* @param {CodeMirrorEditor} cm - Editor.
@@ -278,6 +279,8 @@ if ( 'undefined' === typeof window.wp.codeEditor ) {
return {
getLintOptions,
/**
+ * Initializes the CodeMirror editor.
+ *
* @param {CodeMirrorEditor} editor - Editor instance.
* @return {void}
*/
diff --git a/wp-admin/js/color-picker.js b/wp-admin/js/color-picker.js
index 51d68cbff4..bcf3d0eb84 100644
--- a/wp-admin/js/color-picker.js
+++ b/wp-admin/js/color-picker.js
@@ -5,6 +5,8 @@
*/
/**
+ * Handles the color picker functionality.
+ *
* @param {JQueryStatic} $ The jQuery object.
* @param {undefined} undef The undefined value.
*/
diff --git a/wp-admin/js/edit-comments.js b/wp-admin/js/edit-comments.js
index 4320c8e00f..b6763c3861 100644
--- a/wp-admin/js/edit-comments.js
+++ b/wp-admin/js/edit-comments.js
@@ -2,11 +2,12 @@
/* global commentReply, theExtraList, theList, setCommentsList */
/**
- * Handles updating and editing comments.
* @output wp-admin/js/edit-comments.js
*/
/**
+ * Handles updating and editing comments.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
(function($) {
diff --git a/wp-admin/js/editor-expand.js b/wp-admin/js/editor-expand.js
index 37105aecd8..3e5276ed3e 100644
--- a/wp-admin/js/editor-expand.js
+++ b/wp-admin/js/editor-expand.js
@@ -3,6 +3,8 @@
*/
/**
+ * Handles the editor Distraction-Free Writing (DFW) functionality.
+ *
* @param {Window} window The global window object.
* @param {JQueryStatic} $ The jQuery object.
* @param {undefined} undefined The undefined value.
diff --git a/wp-admin/js/nav-menu.js b/wp-admin/js/nav-menu.js
index b3e6b93f04..f70ca7c99f 100644
--- a/wp-admin/js/nav-menu.js
+++ b/wp-admin/js/nav-menu.js
@@ -1,16 +1,15 @@
/**
- * WordPress Administration Navigation Menu
- * Interface JS functions
- *
- * @version 2.0.0
- *
- * @package WordPress
* @output wp-admin/js/nav-menu.js
*/
/* global menus, postboxes, columns, isRtl, ajaxurl, wpNavMenu */
/**
+ * Handles the WordPress Administration Navigation Menu Interface functionality.
+ *
+ * @version 2.0.0
+ * @package WordPress
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
(function($) {
diff --git a/wp-admin/js/post.js b/wp-admin/js/post.js
index 2eac2f8283..462523636c 100644
--- a/wp-admin/js/post.js
+++ b/wp-admin/js/post.js
@@ -15,6 +15,8 @@ window.makeSlugeditClickable = window.editPermalink = function(){};
window.wp = window.wp || {};
/**
+ * Handles the dynamic functionality needed on post and term pages.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
@@ -256,7 +258,7 @@ window.wp = window.wp || {};
}(jQuery));
/**
- * Heartbeat refresh nonces.
+ * Handles the Heartbeat refresh nonces.
*
* @param {JQueryStatic} $ The jQuery object.
*/
@@ -304,7 +306,7 @@ window.wp = window.wp || {};
}(jQuery));
/**
- * All post and postbox controls and functionality.
+ * Handles all post and postbox controls and functionality.
*
* @param {JQueryStatic} $ The jQuery object.
*/
@@ -1328,7 +1330,7 @@ jQuery( function($) {
} );
/**
- * TinyMCE word count display
+ * Handles the TinyMCE word count display.
*
* @param {JQueryStatic} $ The jQuery object.
* @param {wp.utils.WordCounter} counter The WordCounter object.
diff --git a/wp-admin/js/updates.js b/wp-admin/js/updates.js
index 63235ef717..22e7ac886f 100644
--- a/wp-admin/js/updates.js
+++ b/wp-admin/js/updates.js
@@ -1,15 +1,16 @@
/**
- * Functions for ajaxified updates, deletions and installs inside the WordPress admin.
- *
- * @version 4.2.0
* @output wp-admin/js/updates.js
*/
/* global pagenow, _wpThemeSettings */
/**
+ * Provides functions for ajaxified updates, deletions and installs inside the WordPress admin.
+ *
+ * @version 4.2.0
+ *
* @param {JQueryStatic} $ The jQuery object.
- * @param {Object} wp WP object.
+ * @param {Object} wp The WordPress global object.
* @param {Object} settings WP Updates settings.
* @param {string} settings.ajax_nonce Ajax nonce.
* @param {Object} settings.plugins Base names of plugins in their different states.
diff --git a/wp-admin/js/user-profile.js b/wp-admin/js/user-profile.js
index c2bd1a78dc..e6b79f616f 100644
--- a/wp-admin/js/user-profile.js
+++ b/wp-admin/js/user-profile.js
@@ -5,6 +5,8 @@
*/
/**
+ * Handles the user profile functionality.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
(function($) {
diff --git a/wp-includes/js/api-request.js b/wp-includes/js/api-request.js
index 3404fc8488..a72fd08b37 100644
--- a/wp-includes/js/api-request.js
+++ b/wp-includes/js/api-request.js
@@ -1,3 +1,7 @@
+/**
+ * @output wp-includes/js/api-request.js
+ */
+
/**
* Thin jQuery.ajax wrapper for WP REST API requests.
*
@@ -11,10 +15,7 @@
* @since 4.9.0
* @since 5.6.0 Added overriding of the "PUT" and "DELETE" methods with "POST".
* Added an "application/json" Accept header to all requests.
- * @output wp-includes/js/api-request.js
- */
-
-/**
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
diff --git a/wp-includes/js/customize-base.js b/wp-includes/js/customize-base.js
index 22fd36b4df..2bea9c467d 100644
--- a/wp-includes/js/customize-base.js
+++ b/wp-includes/js/customize-base.js
@@ -227,6 +227,8 @@ window.wp = window.wp || {};
*/
api.Value = api.Class.extend(/** @lends wp.customize.Value.prototype */{
/**
+ * Initializes the Value instance and configures callbacks and options.
+ *
* @param {*} initial The initial value.
* @param {Object} [options] Options to extend the instance with.
*/
diff --git a/wp-includes/js/heartbeat.js b/wp-includes/js/heartbeat.js
index 670d8d047a..e7abe77bb3 100644
--- a/wp-includes/js/heartbeat.js
+++ b/wp-includes/js/heartbeat.js
@@ -1,5 +1,9 @@
/**
- * Heartbeat API
+ * @output wp-includes/js/heartbeat.js
+ */
+
+/**
+ * Handles the Heartbeat API.
*
* Heartbeat is a simple server polling API that sends XHR requests to
* the server every 15 - 60 seconds and triggers events (or callbacks) upon
@@ -24,10 +28,6 @@
* - heartbeat-nonces-expired
*
* @since 3.6.0
- * @output wp-includes/js/heartbeat.js
- */
-
-/**
* @param {JQueryStatic} $ The jQuery object.
* @param {Window} window The global window object.
* @param {undefined} undefined The undefined value.
diff --git a/wp-includes/js/media-editor.js b/wp-includes/js/media-editor.js
index 2cb6277f75..bec97f27f0 100644
--- a/wp-includes/js/media-editor.js
+++ b/wp-includes/js/media-editor.js
@@ -4,8 +4,12 @@
/* global getUserSetting, tinymce, QTags */
-// WordPress, TinyMCE, and Media
-// -----------------------------
+/**
+ * Handles the initialization, refreshing and rendering of media editor components.
+ *
+ * @param {JQueryStatic} $ The jQuery object.
+ * @param {_.UnderscoreStatic} _ The Underscore.js object.
+ */
(function($, _){
/**
* Stores the editors' `wp.media.controller.Frame` instances.
@@ -333,6 +337,8 @@
};
/**
+ * Factory function that creates a media collection controller for managing gallery, playlist, and other media shortcodes.
+ *
* @class wp.media.collection
*
* @param {Object} attributes
diff --git a/wp-includes/js/wp-api.js b/wp-includes/js/wp-api.js
index 8773f4f3ac..a66d96c3fb 100644
--- a/wp-includes/js/wp-api.js
+++ b/wp-includes/js/wp-api.js
@@ -1,9 +1,13 @@
/**
- * @param {Window} window The global window object.
- * @param {undefined} undefined The undefined value.
* @output wp-includes/js/wp-api.js
*/
+/**
+ * Initialize the WordPress REST API client.
+ *
+ * @param {Window} window The global window object.
+ * @param {undefined} undefined The undefined value.
+ */
(function( window, undefined ) {
'use strict';
@@ -33,6 +37,12 @@
})( window );
+/**
+ * Sets up the WordPress REST API client with utilities and Backbone model mixins for managing API resources.
+ *
+ * @param {Window} window The global window object.
+ * @param {undefined} undefined The undefined value.
+ */
(function( window, undefined ) {
'use strict';
@@ -826,6 +836,10 @@
// Suppress warning about parse function's unused "options" argument:
/* jshint unused:false */
+
+/**
+ * Creates the base Backbone model for WordPress REST API.
+ */
(function() {
'use strict';
@@ -978,6 +992,9 @@
);
})();
+/**
+ * Creates the base Backbone collection for WordPress REST API.
+ */
( function() {
'use strict';
@@ -1135,6 +1152,9 @@
} )();
+/**
+ * Constructs Backbone models and collections from the WordPress REST API schema.
+ */
( function() {
'use strict';
diff --git a/wp-includes/js/wp-auth-check.js b/wp-includes/js/wp-auth-check.js
index f01b14b35e..1617da0cb2 100644
--- a/wp-includes/js/wp-auth-check.js
+++ b/wp-includes/js/wp-auth-check.js
@@ -1,10 +1,10 @@
/**
- * Interim login dialog.
- *
* @output wp-includes/js/wp-auth-check.js
*/
/**
+ * Handles the interim login dialog.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
diff --git a/wp-includes/js/wp-list-revisions.js b/wp-includes/js/wp-list-revisions.js
index 80ce2e909f..ae5ad321ef 100644
--- a/wp-includes/js/wp-list-revisions.js
+++ b/wp-includes/js/wp-list-revisions.js
@@ -1,8 +1,13 @@
/**
- * @param {Window} w The global window object.
* @output wp-includes/js/wp-list-revisions.js
*/
+/**
+ * Hides the revisions radio buttons to stop selecting reverse comparisons
+ *
+ * @param {Window} w The global window object.
+ */
+
(function(w) {
var init = function() {
var pr = document.getElementById('post-revisions'),
diff --git a/wp-includes/js/wp-lists.js b/wp-includes/js/wp-lists.js
index c81848ff5d..3f667a0434 100644
--- a/wp-includes/js/wp-lists.js
+++ b/wp-includes/js/wp-lists.js
@@ -5,6 +5,8 @@
/* global ajaxurl, wpAjax */
/**
+ * Handles the dynamic functionality needed for lists.
+ *
* @param {JQueryStatic} $ The jQuery object.
*/
( function( $ ) {
diff --git a/wp-includes/js/wp-sanitize.js b/wp-includes/js/wp-sanitize.js
index d67bc0b77a..c5c97f6c37 100644
--- a/wp-includes/js/wp-sanitize.js
+++ b/wp-includes/js/wp-sanitize.js
@@ -2,6 +2,9 @@
* @output wp-includes/js/wp-sanitize.js
*/
+/**
+ * Provides helper functions to sanitize strings.
+ */
( function () {
window.wp = window.wp || {};
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 920fde9cc6..f63145e1de 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-alpha-63513';
+$wp_version = '7.2-alpha-63514';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.