From d8df21399ff9389319efd5adf8c1ea8557b8b101 Mon Sep 17 00:00:00 2001
From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Wed, 7 Oct 2020 03:46:50 +0100
Subject: [PATCH] docs: add the flush option for $watch

---
 src/api/instance-methods.md | 19 +++++++++++++++++++
 src/api/options-data.md     |  2 +-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/api/instance-methods.md b/src/api/instance-methods.md
index 86b5516010..fb9bc0f04d 100644
--- a/src/api/instance-methods.md
+++ b/src/api/instance-methods.md
@@ -9,6 +9,7 @@
   - `{Object} options (optional)`
     - `{boolean} deep`
     - `{boolean} immediate`
+    - `{string} flush`
 
 - **Returns:** `{Function} unwatch`
 
@@ -172,6 +173,24 @@
   )
   ```
 
+- **Option: flush**
+
+  The `flush` option allows for greater control over the timing of the callback. It can be set to `'pre'`, `'post'` or `'sync'`.
+  
+  The default value is `'pre'`, which specifies that the callback should be invoked before rendering. This allows the callback to update other values before the template runs.
+  
+  The value `'post'` can be used to defer the callback until after rendering. This should be used if the callback needs access to the updated DOM or child components via `$refs`.
+
+  If `flush` is set to `'sync'`, the callback will be called synchronously, as soon as the value changes.
+
+  For both `'pre'` and `'post'`, the callback is buffered using a queue. The callback will only be added to the queue once, even if the watched value changes multiple times. The interim values will be skipped and won't be passed to the callback.
+  
+  Buffering the callback not only improves performance but also helps to ensure data consistency. The watchers won't be triggered until the code performing the data updates has finished.
+  
+  `'sync'` watchers should be used sparingly, as they don't have these benefits.
+
+  For more information about `flush` see [Effect Flush Timing](../guide/reactivity-computed-watchers.html#effect-flush-timing).
+
 - **See also:** [Watchers](../guide/computed.html#watchers)
 
 ## $emit
diff --git a/src/api/options-data.md b/src/api/options-data.md
index f95e143a84..d2dc87318e 100644
--- a/src/api/options-data.md
+++ b/src/api/options-data.md
@@ -177,7 +177,7 @@
 
 - **Details:**
 
-  An object where keys are expressions to watch and values are the corresponding callbacks. The value can also be a string of a method name, or an Object that contains additional options. The component instance will call `$watch()` for each entry in the object at instantiation.
+  An object where keys are expressions to watch and values are the corresponding callbacks. The value can also be a string of a method name, or an Object that contains additional options. The component instance will call `$watch()` for each entry in the object at instantiation. See [$watch](instance-methods.html#watch) for more information about the `deep`, `immediate` and `flush` options.
 
 - **Example:**