Changeset 63791

Timestamp:

09/22/2026 07:35:23 AM (less than one hour ago)

Author:

afercia

Message:

General: Better documentation for the sync functions in the wp api.js file.

Amends [63766]. Better document the options param and return tag for the sync functions in src/js/_enqueues/wp/api.js.

Part of the effort to improve JS inline documentation for 7.2.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13650

Props westonruter, afercia.
See #66033.

File:

• trunk/src/js/_enqueues/wp/api.js (modified) (2 diffs)

trunk/src/js/_enqueues/wp/api.js

@@ -867 +867 @@
 
                         /**
-                         * Set nonce header before every Backbone sync.
+                         * Sets a nonce header before every Backbone sync.
                          *
-                         * @param {string}         method  The CRUD method ("create", "read", "update", or "delete") to be performed.
-                         * @param {Backbone.Model} model   The model to be synced.
-                         * @param {Object}         options Additional options for the sync.
-                         * @return {*}.
+                         * @param {string}         method               The CRUD method ("create", "read", "update", or "delete") to be performed.
+                         * @param {Backbone.Model} model                The model to be synced.
+                         * @param {Object}         options              Additional options for the sync.
+                         * @param {Function}       [options.beforeSend] A function to be called before sending the request.
+                         * @param {Function}       [options.complete]   A function to be called when the request completes.
+                         * @return {JQuery.Promise} A promise that resolves when the sync operation completes.
                          */
                         sync: function( method, model, options ) {
@@ -1028 +1030 @@
 
                         /**
-                         * Extend Backbone.Collection.sync to add nonce and pagination support.
+                         * Extends Backbone.Collection.sync to add nonce and pagination support.
                          *
-                         * Set nonce header before every Backbone sync.
+                         * Sets a nonce header before every Backbone sync.
                          *
-                         * @param {string}         method  The CRUD method ("create", "read", "update", or "delete") to be performed.
-                         * @param {Backbone.Model} model   The model to be synced.
-                         * @param {Object}         options Additional options for the sync.
-                         * @return {*}.
+                         * @param {string}         method               The CRUD method ("create", "read", "update", or "delete") to be performed.
+                         * @param {Backbone.Model} model                The model to be synced.
+                         * @param {Object}         options              Additional options for the sync.
+                         * @param {Function}       [options.beforeSend] A function to be called before sending the request.
+                         * @param {Function}       [options.success]    A function to be called when the request succeeds.
+                         * @param {Function}       [options.complete]   A function to be called when the request completes, regardless of success or failure.
+                         * @param {Object}         [options.data]       Data to be sent with the request.
+                         * @return {JQuery.Promise} A promise that resolves when the sync operation completes.
                          */
                         sync: function( method, model, options ) {