fix: revise the migration guide for the emits option (vuejs#690)

Author: skirtles-code

src/guide/migration/emits-option.md

@@ -8,13 +8,13 @@ badges:
 
 ## Overview
 
-Vue 3 now offers an `emits` option similar to the existing `props` option. This option can be used to define the events that a component can emit to its parent.
+Vue 3 now offers an `emits` option, similar to the existing `props` option. This option can be used to define the events that a component can emit to its parent.
 
 ## 2.x Behavior
 
-In Vue 2, you can define the props that a component received, but you can't declare which events it can emit:
+In Vue 2, you can define the props that a component receives, but you can't declare which events it can emit:
 
-```html
+```vue
 <template>
   <div>
     <p>{{ text }}</p>
@@ -30,12 +30,14 @@ In Vue 2, you can define the props that a component received, but you can't decl
 
 ## 3.x Behavior
 
-Similar to props, the events that the component emits can now be defined with the `emits` option.
+Similar to props, the events that the component emits can now be defined with the `emits` option:
 
-```html
+```vue
 <template>
-  <p>{{ text }}</p>
-  <button v-on:click="$emit('accepted')">OK</button>
+  <div>
+    <p>{{ text }}</p>
+    <button v-on:click="$emit('accepted')">OK</button>
+  </div>
 </template>
 <script>
   export default {
@@ -45,28 +47,26 @@ Similar to props, the events that the component emits can now be defined with th
 </script>
 ```
 
-The option also accepts an object notation, which allows the developer to define validators for the arguments that are passed with the emitted event, similar to validators in props definitions.
+The option also accepts an object, which allows the developer to define validators for the arguments that are passed with the emitted event, similar to validators in `props` definitions.
 
 For more information on this, please read the [API documentation for this feature](../../api/options-data.md#emits).
 
 ## Migration Strategy
 
-It is highly recommended that you document all of the emitted events by your each of components this way because of the [removal of the `.native` modifier](./v-on-native-modifier-removed.md).
+It is highly recommended that you document all of the events emitted by each of your components using `emits`.
 
-All events not defined with `emits` are now added as DOM event listeners to the component's root node (unless `inheritAttrs: false` has been set).
+This is especially important because of [the removal of the `.native` modifier](./v-on-native-modifier-removed.md). Any listeners for events that aren't declared with `emits` will now be included in the component's `$attrs`, which by default will be bound to the component's root node.
 
 ### Example
 
 For components that re-emit native events to their parent, this would now lead to two events being fired:
 
 ```vue
 <template>
-  <p>{{ text }}</p>
   <button v-on:click="$emit('click', $event)">OK</button>
 </template>
 <script>
 export default {
-  props: ['text'],
   emits: [] // without declared event
 }
 </script>
@@ -80,18 +80,18 @@ When a parent listens for the `click` event on the component:
 
 it would now be triggered _twice_:
 
-- Once from `$emit()`
-- Once from a native event listener applied to the root element
+- Once from `$emit()`.
+- Once from a native event listener applied to the root element.
 
 Here you have two options:
 
-1. Properly declare the `click` event. This is useful if you actually do add some logic to that event handler in `<my-button>`
+1. Properly declare the `click` event. This is useful if you actually do add some logic to that event handler in `<my-button>`.
 2. Remove the re-emitting of the event, since the parent can now listen for the native event easily, without adding `.native`. Suitable when you really only re-emit the event anyway.
 
 ## See also
 
 - [Relevant RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0030-emits-option.md)
 - [Migration guide - `.native` modifier removed](./v-on-native-modifier-removed.md)
 - [Migration guide - `$listeners` removed](./listeners-removed.md)
-- [Migration guide - `$attrs` includes `class` & `style` ](./attrs-includes-class-style.md)
+- [Migration guide - `$attrs` includes `class` & `style`](./attrs-includes-class-style.md)
 - [Migration guide - Changes in the Render Functions API](./render-function-api.md)