Finishing touches

packages/search-ui/src/DebounceManager.js

@@ -38,11 +38,11 @@ class DebounceManager {
   }
 
   /**
-   * Cancels existing debounced functions from executing.
+   * Cancels existing debounced function calls.
    *
-   * This will cancel any call to the function, regardless of the debounce length that was provided.
+   * This will cancel any debounced function call, regardless of the debounce length that was provided.
    *
-   * For example, calling the following series of debounce calls will create multiple debounced functions, because
+   * For example, making the following series of calls will create multiple debounced functions, because
    * they are cached by a combination of unique name and debounce length.
    *
    * runWithDebounce(1000, "_updateSearchResults", this._updateSearchResults)
@@ -54,7 +54,7 @@ class DebounceManager {
    * cancelByName("_updateSearchResults")
    *
    * @param {string} functionName The name of the function that was debounced. This needs to match exactly what was provided
-   * runWithDebounce was called originally.
+   * when runWithDebounce was called originally.
    */
   cancelByName(functionName) {
     Object.entries(this.debounceCache)

packages/search-ui/src/SearchDriver.js

@@ -224,10 +224,12 @@ export default class SearchDriver {
       ...searchParameters
     };
 
-    // We want to make sure if this method is running, that any calls to this
-    // method that had been previously deferred with `runWithDebounce` are cancelled. We don't want the
-    // possibly have the deferred call execute after this immediate call. For example, this method
-    // is called in this way from the setSearchTerm action.
+    // State updates should always be applied in the order that they are made. This function, _updateSearchResults,
+    // makes state updates.
+    // In the case where a call to "_updateSearchResults" was made and delayed for X amount of time using
+    // `debounceManager.runWithDebounce`, and a subsequent call is made _updateSearchResults before that delay ends, we
+    // want to make sure that outstanding call to "_updateSearchResults" is cancelled, as it would apply state updates
+    // out of order.
     this.debounceManager.cancelByName("_updateSearchResults");
 
     this._setState({

packages/search-ui/src/__tests__/actions/setSearchTerm.test.js

@@ -148,8 +148,6 @@ describe("#setSearchTerm", () => {
     jest.runAllTimers();
     expect(updatedStateAfterAction.state.current).toBe(2);
     driver.setSearchTerm("term");
-    // Note that current is set to 1 by the request state update, and we did
-    // not have to wait any amount of time, it was executed immediately.
     expect(updatedStateAfterAction.state.current).toBe(1);
   });