From 423c3ac20f26dd2d30675d6f2038d7e350c0cf43 Mon Sep 17 00:00:00 2001
From: Ben Randall <veleek@gmail.com>
Date: Tue, 21 Sep 2021 11:15:24 -0700
Subject: [PATCH 1/2] Improved documentation for `reload*` values

I've run into a few issues trying to figure out what the correct values are for the various `reload*` configuration values.  I've added some more detail to parameter documentation and updated it to be more consistent between the three values.
---
 packages/browser-sync/lib/default-config.js | 24 +++++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/packages/browser-sync/lib/default-config.js b/packages/browser-sync/lib/default-config.js
index eca62e1c9..81fc1fa51 100644
--- a/packages/browser-sync/lib/default-config.js
+++ b/packages/browser-sync/lib/default-config.js
@@ -411,9 +411,11 @@ module.exports = {
     scrollElementMapping: [],
 
     /**
-     * Time, in milliseconds, to wait before
-     * instructing the browser to reload/inject following a
-     * file change event
+     * Time, in milliseconds, to wait before instructing the browser to 
+     * reload/inject following a file change event.  This allows time for
+     * any other processing that may need to occur after the initial event.
+     * Unlike `reloadDebounce` this does not _prevent_ a reload from 
+     * occurring, it just offsets the reload time from the event.
      * @property reloadDelay
      * @type Number
      * @default 0
@@ -421,8 +423,11 @@ module.exports = {
     reloadDelay: 0,
 
     /**
-     * Wait for a specified window of event-silence before
-     * sending any reload events.
+     * Time, in milliseconds, to wait since the most recent change event 
+     * before sending any reload events.  If this value is set too high and
+     * changes occur slowly over a long period of item, this may delay
+     * browser reload for a long time but can minimize the total number of
+     * reloads triggered.
      * @property reloadDebounce
      * @type Number
      * @default 0
@@ -431,8 +436,13 @@ module.exports = {
     reloadDebounce: 500,
 
     /**
-     * Emit only the first event during sequential time windows
-     * of a specified duration.
+     * Time, in milliseconds, to wait after processing a change event before
+     * processing the next one.  If this is set to 0, all events will be
+     * processed as soon as they occur (taking into account the `relayDelay`
+     * and `relayDebounce` values).  If there are many change events around 
+     * the same time, setting this to a non-zero value will cause them to be
+     * processed one at a time with a delay and (potentially) a browser reload
+     * each time.
      * @property reloadThrottle
      * @type Number
      * @default 0

From afc3eb9c4f730d19b9d24e4c269cc8093484daa4 Mon Sep 17 00:00:00 2001
From: Ben Randall <veleek@gmail.com>
Date: Tue, 21 Sep 2021 11:20:46 -0700
Subject: [PATCH 2/2] Update docs for default value for `reloadDebounce`

---
 packages/browser-sync/lib/default-config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/browser-sync/lib/default-config.js b/packages/browser-sync/lib/default-config.js
index 81fc1fa51..2a6451b96 100644
--- a/packages/browser-sync/lib/default-config.js
+++ b/packages/browser-sync/lib/default-config.js
@@ -430,7 +430,7 @@ module.exports = {
      * reloads triggered.
      * @property reloadDebounce
      * @type Number
-     * @default 0
+     * @default 500
      * @since 2.6.0
      */
     reloadDebounce: 500,