1 files changed, 28 insertions, 16 deletions

diff --git a/core/misc/debounce.js b/core/misc/debounce.js
index eb1f069e0de..e77940b9efa 100644
--- a/core/misc/debounce.js
+++ b/core/misc/debounce.js
@@ -1,36 +1,48 @@
 /**
-* DO NOT EDIT THIS FILE.
-* See the following change record for more information,
-* https://www.drupal.org/node/2815083
-* @preserve
-**/
+ * @file
+ * Adapted from underscore.js with the addition Drupal namespace.
+ */
 
+/**
+ * Limits the invocations of a function in a given time frame.
+ *
+ * The debounce function wrapper should be used sparingly. One clear use case
+ * is limiting the invocation of a callback attached to the window resize event.
+ *
+ * Before using the debounce function wrapper, consider first whether the
+ * callback could be attached to an event that fires less frequently or if the
+ * function can be written in such a way that it is only invoked under specific
+ * conditions.
+ *
+ * @param {function} func
+ *   The function to be invoked.
+ * @param {number} wait
+ *   The time period within which the callback function should only be
+ *   invoked once. For example if the wait period is 250ms, then the callback
+ *   will only be called at most 4 times per second.
+ * @param {bool} immediate
+ *   Whether we wait at the beginning or end to execute the function.
+ *
+ * @return {function}
+ *   The debounced function.
+ */
 Drupal.debounce = function (func, wait, immediate) {
   let timeout;
   let result;
-  return function () {
-    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
-      args[_key] = arguments[_key];
-    }
-
+  return function (...args) {
     const context = this;
-
     const later = function () {
       timeout = null;
-
       if (!immediate) {
         result = func.apply(context, args);
       }
     };
-
     const callNow = immediate && !timeout;
     clearTimeout(timeout);
     timeout = setTimeout(later, wait);
-
     if (callNow) {
       result = func.apply(context, args);
     }
-
     return result;
   };
-};
\ No newline at end of file
+};