From 190ab872937ca57881c28e4a97571486dda3f03e Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Fri, 18 Sep 2020 00:07:54 -0400
Subject: [PATCH] docs: update watch behavior adjustments

---
 src/guide/migration/introduction.md       |  2 +-
 src/guide/reactivity-computed-watchers.md | 12 +++++++-----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/guide/migration/introduction.md b/src/guide/migration/introduction.md
index d90cd0a1e6..43b37281e6 100644
--- a/src/guide/migration/introduction.md
+++ b/src/guide/migration/introduction.md
@@ -92,7 +92,7 @@ The following consists a list of breaking changes from 2.x:
 - [The `data` option from mixins is now merged shallowly](/guide/migration/data-option.html#mixin-merge-behavior-change)
 - [Attributes coercion strategy changed](/guide/migration/attribute-coercion.html)
 - [Some transition classes got a rename](/guide/migration/transition.html)
-- [Component watch option](/api/options-data.html#watch) and [instance method `$watch`](/api/instance-methods.html#watch) no longer supports dot-delimited string paths, use a computed function as the parameter instead.
+- When using [the `watch` option](/api/options-data.html#watch) to watch an array, the callback will only trigger when the array is replaced, and no longer trigger on array mutation. To trigger on mutation, the `deep` option must be specified. This is a side effect of more precise dependency tracking in Vue 3.
 - `<template>` tags with no special directives (`v-if/else-if/else`, `v-for`, or `v-slot`) are now treated as plain elements and will result in a native `<template>` element instead of rendering its inner content.
 - In Vue 2.x, application root container's `outerHTML` is replaced with root component template (or eventually compiled to a template, if root component has no template/render option). Vue 3.x now uses application container's `innerHTML` instead - this means the container itself is no longer considered part of the template.
 
diff --git a/src/guide/reactivity-computed-watchers.md b/src/guide/reactivity-computed-watchers.md
index 28168d9ea9..a6ff07157f 100644
--- a/src/guide/reactivity-computed-watchers.md
+++ b/src/guide/reactivity-computed-watchers.md
@@ -93,7 +93,7 @@ An async function implicitly returns a Promise, but the cleanup function needs t
 
 ### Effect Flush Timing
 
-Vue's reactivity system buffers invalidated effects and flushes them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's `update` function is also a watched effect. When a user effect is queued, it is always invoked after all component `update` effects:
+Vue's reactivity system buffers invalidated effects and flushes them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's `update` function is also a watched effect. When a user effect is queued, it is by default invoked **before** all component `update` effects:
 
 ```html
 <template>
@@ -120,7 +120,7 @@ Vue's reactivity system buffers invalidated effects and flushes them asynchronou
 In this example:
 
 - The count will be logged synchronously on initial run.
-- When `count` is mutated, the callback will be called **after** the component has updated.
+- When `count` is mutated, the callback will be called **before** the component has updated.
 
 Note the first run is executed before the component is mounted. So if you wish to access the DOM (or template refs) in a watched effect, do it in the `onMounted` hook:
 
@@ -132,7 +132,7 @@ onMounted(() => {
 })
 ```
 
-In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional `options` object with the `flush` option (default is `'post'`):
+In cases where a watcher effect needs to be re-run synchronously or after component updates, we can pass an additional `options` object with the `flush` option (default is `'pre'`):
 
 ```js
 // fire synchronously
@@ -145,13 +145,15 @@ watchEffect(
   }
 )
 
-// fire before component updates
+// fire after component updates so you can access the updated DOM
+// Note: this will also defer the initial run of the effect until the
+// component's first render is finished.
 watchEffect(
   () => {
     /* ... */
   },
   {
-    flush: 'pre'
+    flush: 'post'
   }
 )
 ```