docs(zh): update zh docs from en docs (#2150)

* docs(zh): update zh docs from en docs

* Update docs/zh/api/index.md

Co-authored-by: Jinjiang <zhaojinjiang@me.com>

* docs(zh): apply suggestions

* docs: apply suggestions

Co-authored-by: Jinjiang <zhaojinjiang@me.com>

docs/zh/api/index.md

@@ -40,9 +40,7 @@ sidebar: auto
 
 - 类型: `{ [type: string]: Function }`
 
-  在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数，`payload` 作为第二个参数（可选）。
-
-  `context` 对象包含以下属性：
+  在 store 上注册 action。处理函数总是接受 `context` 作为第一个参数，`context` 对象包含以下属性：
 
   ``` js
   {
@@ -67,15 +65,15 @@ sidebar: auto
 
   ```
   state,     // 如果在模块中定义则为模块的局部状态
-  getters,   // 等同于 store.getters
+  getters    // 等同于 store.getters
   ```
 
   当定义在一个模块里时会特别一些：
 
   ```
   state,       // 如果在模块中定义则为模块的局部状态
-  getters,     // 等同于 store.getters
-  rootState    // 等同于 store.state
+  getters,     // 当前模块的局部 getters
+  rootState,   // 全局 state
   rootGetters  // 所有 getters
   ```
 
@@ -89,12 +87,12 @@ sidebar: auto
 
   包含了子模块的对象，会被合并到 store，大概长这样：
 
-  ``` js
+  ```js
   {
     key: {
       state,
       namespaced?,
-      mutations,
+      mutations?,
       actions?,
       getters?,
       modules?
@@ -130,7 +128,7 @@ sidebar: auto
 
   为某个特定的 Vuex 实例打开或关闭 devtools。对于传入 `false` 的实例来说 Vuex store 不会订阅到 devtools 插件。对于一个页面中有多个 store 的情况非常有用。
 
-  ``` js
+  ```js
   {
     devtools: false
   }
@@ -154,15 +152,15 @@ sidebar: auto
 
 ### commit
 
-- `commit(type: string, payload?: any, options?: Object)`
-- `commit(mutation: Object, options?: Object)`
+-  `commit(type: string, payload?: any, options?: Object)`
+-  `commit(mutation: Object, options?: Object)`
 
   提交 mutation。`options` 里可以有 `root: true`，它允许在[命名空间模块](../guide/modules.md#命名空间)里提交根的 mutation。[详细介绍](../guide/mutations.md)
 
 ### dispatch
 
-- `dispatch(type: string, payload?: any, options?: Object): Promise<any>`
-- `dispatch(action: Object, options?: Object): Promise<any>`
+-  `dispatch(type: string, payload?: any, options?: Object): Promise<any>`
+-  `dispatch(action: Object, options?: Object): Promise<any>`
 
   分发 action。`options` 里可以有 `root: true`，它允许在[命名空间模块](../guide/modules.md#命名空间)里分发根的 action。返回一个解析所有被触发的 action 处理器的 Promise。[详细介绍](../guide/actions.md)
 
@@ -174,58 +172,66 @@ sidebar: auto
 
 ### watch
 
-- `watch(fn: Function, callback: Function, options?: Object): Function`
+-  `watch(fn: Function, callback: Function, options?: Object): Function`
 
   响应式地侦听 `fn` 的返回值，当值改变时调用回调函数。`fn` 接收 store 的 state 作为第一个参数，其 getter 作为第二个参数。最后接收一个可选的对象参数表示 Vue 的 [`vm.$watch`](https://cn.vuejs.org/v2/api/#vm-watch) 方法的参数。
 
   要停止侦听，调用此方法返回的函数即可停止侦听。
 
 ### subscribe
 
-- `subscribe(handler: Function, options?: Object): Function`
+-  `subscribe(handler: Function, options?: Object): Function`
 
   订阅 store 的 mutation。`handler` 会在每个 mutation 完成后调用，接收 mutation 和经过 mutation 后的状态作为参数：
 
-  ``` js
-  store.subscribe((mutation, state) => {
+  ```js
+  const unsubscribe = store.subscribe((mutation, state) => {
     console.log(mutation.type)
     console.log(mutation.payload)
   })
+
+  // 你可以调用 unsubscribe 来停止订阅。
+  unsubscribe()
   ```
 
   默认情况下，新的处理函数会被添加到其链的尾端，因此它会在其它之前已经被添加了的处理函数之后执行。这一行为可以通过向 `options` 添加 `prepend: true` 来覆写，即把处理函数添加到其链的最开始。
 
-  ``` js
+  ```js
   store.subscribe(handler, { prepend: true })
   ```
-  要停止订阅，调用此方法返回的函数即可停止订阅。
+ 
+ `subscribe` 方法将返回一个 `unsubscribe` 函数，当不再需要订阅时应该调用该函数。例如，你可能会订阅一个 Vuex 模块，当你取消注册该模块时取消订阅。或者你可能从一个 Vue 组件内部调用 `subscribe`，然后不久就会销毁该组件。在这些情况下，你应该记得手动取消订阅。
 
   通常用于插件。[详细介绍](../guide/plugins.md)
 
 ### subscribeAction
 
-- `subscribeAction(handler: Function, options?: Object): Function`
+-  `subscribeAction(handler: Function, options?: Object): Function`
 
-  订阅 store 的 action。`handler` 会在每个 action 分发的时候调用并接收 action 描述和当前的 store 的 state 这两个参数：
+  订阅 store 的 action。`handler` 会在每个 action 分发的时候调用并接收 action 描述和当前的 store 的 state 这两个参数。
+  `subscribe` 方法将返回一个 `unsubscribe` 函数，当不再需要订阅时，应调用该函数。例如，当取消注册一个 Vuex 模块或销毁一个 Vue 组件之前。
 
-  ``` js
-  store.subscribeAction((action, state) => {
+  ```js
+  const unsubscribe = store.subscribeAction((action, state) => {
     console.log(action.type)
     console.log(action.payload)
   })
+
+  // 你可以调用 unsubscribe 来停止订阅。
+  unsubscribe()
   ```
 
   默认情况下，新的处理函数会被添加到其链的尾端，因此它会在其它之前已经被添加了的处理函数之后执行。这一行为可以通过向 `options` 添加 `prepend: true` 来覆写，即把处理函数添加到其链的最开始。
 
-  ``` js
+  ```js
   store.subscribeAction(handler, { prepend: true })
   ```
 
-  要停止订阅，调用此方法返回的函数即可停止订阅。
+  `subscribeAction` 方法将返回一个 `unsubscribe` 函数，当不再需要订阅时，应该调用该函数。例如，你可能会订阅一个 Vuex 模块，并在取消注册该模块时取消订阅。或者你可能从 Vue 组件内部调用`subscribeAction`，然后不久就会销毁该组件。在这些情况下，你应该记得手动取消订阅。
 
   `subscribeAction` 也可以指定订阅处理函数的被调用时机应该在一个 action 分发*之前*还是*之后* (默认行为是*之前*)：
 
-  ``` js
+  ```js
   store.subscribeAction({
     before: (action, state) => {
       console.log(`before action ${action.type}`)
@@ -238,7 +244,7 @@ sidebar: auto
 
   `subscribeAction` 也可以指定一个 `error` 处理函数以捕获分发 action 的时候被抛出的错误。该函数会从第三个参数接收到一个 `error` 对象。
 
-  ``` js
+  ```js
   store.subscribeAction({
     error: (action, state, error) => {
       console.log(`error action ${action.type}`)
@@ -251,15 +257,15 @@ sidebar: auto
 
 ### registerModule
 
-- `registerModule(path: string | Array<string>, module: Module, options?: Object)`
+-  `registerModule(path: string | Array<string>, module: Module, options?: Object)`
 
   注册一个动态模块。[详细介绍](../guide/modules.md#模块动态注册)
 
   `options` 可以包含 `preserveState: true` 以允许保留之前的 state。用于服务端渲染。
 
 ### unregisterModule
 
-- `unregisterModule(path: string | Array<string>)`
+-  `unregisterModule(path: string | Array<string>)`
 
   卸载一个动态模块。[详细介绍](../guide/modules.md#模块动态注册)
 
@@ -271,15 +277,15 @@ sidebar: auto
 
 ### hotUpdate
 
-- `hotUpdate(newOptions: Object)`
+-  `hotUpdate(newOptions: Object)`
 
   热替换新的 action 和 mutation。[详细介绍](../guide/hot-reload.md)
 
 ## 组件绑定的辅助函数
 
 ### mapState
 
-- `mapState(namespace?: string, map: Array<string> | Object<string | function>): Object`
+-  `mapState(namespace?: string, map: Array<string> | Object<string | function>): Object`
 
   为组件创建计算属性以返回 Vuex store 中的状态。[详细介绍](../guide/state.md#mapstate-辅助函数)
 
@@ -289,15 +295,15 @@ sidebar: auto
 
 ### mapGetters
 
-- `mapGetters(namespace?: string, map: Array<string> | Object<string>): Object`
+-  `mapGetters(namespace?: string, map: Array<string> | Object<string>): Object`
 
   为组件创建计算属性以返回 getter 的返回值。[详细介绍](../guide/getters.md#mapgetters-辅助函数)
 
   第一个参数是可选的，可以是一个命名空间字符串。[详细介绍](../guide/modules.md#带命名空间的绑定函数)
 
 ### mapActions
 
-- `mapActions(namespace?: string, map: Array<string> | Object<string | function>): Object`
+-  `mapActions(namespace?: string, map: Array<string> | Object<string | function>): Object`
 
   创建组件方法分发 action。[详细介绍](../guide/actions.md#在组件中分发-action)
 
@@ -307,7 +313,7 @@ sidebar: auto
 
 ### mapMutations
 
-- `mapMutations(namespace?: string, map: Array<string> | Object<string | function>): Object`
+-  `mapMutations(namespace?: string, map: Array<string> | Object<string | function>): Object`
 
   创建组件方法提交 mutation。[详细介绍](../guide/mutations.md#在组件中提交-mutation)
 
@@ -378,7 +384,7 @@ sidebar: auto
   最后，将 key 传递给 `useStore` 方法以获取指定类型的 store 实例。
 
   ```ts
-  // vue 组件
+  // 在 vue 组件内
   import { useStore } from 'vuex'
   import { key } from './store'
 

docs/zh/guide/actions.md

@@ -81,7 +81,8 @@ actions: {
   checkout ({ commit, state }, products) {
     // 把当前购物车的物品备份起来
     const savedCartItems = [...state.cart.added]
-    // 发出结账请求，然后乐观地清空购物车
+    // 发出结账请求
+    // 然后乐观地清空购物车
     commit(types.CHECKOUT_REQUEST)
     // 购物 API 接受一个成功回调和一个失败回调
     shop.buyProducts(

docs/zh/guide/forms.md

@@ -15,6 +15,7 @@
 ``` html
 <input :value="message" @input="updateMessage">
 ```
+
 ``` js
 // ...
 computed: {
@@ -47,6 +48,7 @@ mutations: {
 ``` html
 <input v-model="message">
 ```
+
 ``` js
 // ...
 computed: {

docs/zh/guide/getters.md

@@ -17,7 +17,7 @@ computed: {
 Vuex 允许我们在 store 中定义“getter”（可以认为是 store 的计算属性）。
 
 ::: warning 注意
-从 Vue 3.0 开始，getter 的结果不再像计算属性一样会被缓存起来。这是一个已知的问题，将会在 3.2 版本中修复。详情请看 [PR #1878](https://github.com/vuejs/vuex/pull/1883)。
+从 Vue 3.0 开始，getter 的结果不再像计算属性一样会被缓存起来。这是一个已知的问题，将会在 3.1 版本中修复。详情请看 [PR #1878](https://github.com/vuejs/vuex/pull/1883)。
 :::
 
 Getter 接受 state 作为其第一个参数：
@@ -31,7 +31,7 @@ const store = createStore({
     ]
   },
   getters: {
-    doneTodos: (state) => {
+    doneTodos (state) {
       return state.todos.filter(todo => todo.done)
     }
   }

docs/zh/guide/modules.md

@@ -46,7 +46,6 @@ const moduleA = {
       state.count++
     }
   },
-
   getters: {
     doubleCount (state) {
       return state.count * 2
@@ -151,6 +150,7 @@ modules: {
       someGetter (state, getters, rootState, rootGetters) {
         getters.someOtherGetter // -> 'foo/someOtherGetter'
         rootGetters.someOtherGetter // -> 'someOtherGetter'
+        rootGetters['bar/someOtherGetter'] // -> 'bar/someOtherGetter'
       },
       someOtherGetter: state => { ... }
     },
@@ -161,6 +161,7 @@ modules: {
       someAction ({ dispatch, commit, getters, rootGetters }) {
         getters.someGetter // -> 'foo/someGetter'
         rootGetters.someGetter // -> 'someGetter'
+        rootGetters['bar/someGetter'] // -> 'bar/someGetter'
 
         dispatch('someOtherAction') // -> 'foo/someOtherAction'
         dispatch('someOtherAction', null, { root: true }) // -> 'someOtherAction'
@@ -209,7 +210,11 @@ computed: {
   ...mapState({
     a: state => state.some.nested.module.a,
     b: state => state.some.nested.module.b
-  })
+  }),
+  ...mapGetters([
+    'some/nested/module/someGetter', // -> this['some/nested/module/someGetter']
+    'some/nested/module/someOtherGetter', // -> this['some/nested/module/someOtherGetter']
+  ])
 },
 methods: {
   ...mapActions([
@@ -226,7 +231,11 @@ computed: {
   ...mapState('some/nested/module', {
     a: state => state.a,
     b: state => state.b
-  })
+  }),
+  ...mapGetters('some/nested/module', [
+    'someGetter', // -> this.someGetter
+    'someOtherGetter', // -> this.someOtherGetter
+  ])
 },
 methods: {
   ...mapActions('some/nested/module', [
@@ -290,6 +299,7 @@ const store = createStore({ /* 选项 */ })
 store.registerModule('myModule', {
   // ...
 })
+
 // 注册嵌套模块 `nested/myModule`
 store.registerModule(['nested', 'myModule'], {
   // ...

docs/zh/guide/mutations.md

@@ -36,6 +36,7 @@ mutations: {
   }
 }
 ```
+
 ``` js
 store.commit('increment', 10)
 ```
@@ -95,7 +96,8 @@ import { SOME_MUTATION } from './mutation-types'
 const store = createStore({
   state: { ... },
   mutations: {
-    // 我们可以使用 ES2015 风格的计算属性命名功能来使用一个常量作为函数名
+    // 我们可以使用 ES2015 风格的计算属性命名功能
+    // 来使用一个常量作为函数名
     [SOME_MUTATION] (state) {
       // 修改 state
     }

docs/zh/guide/plugins.md

@@ -27,7 +27,7 @@ const store = createStore({
 
 在插件中不允许直接修改状态——类似于组件，只能通过提交 mutation 来触发变化。
 
-通过提交 mutation，插件可以用来同步数据源到 store。例如，同步 websocket 数据源到 store（下面是个大概例子，实际上 `createPlugin` 方法可以有更多选项来完成复杂任务）：
+通过提交 mutation，插件可以用来同步数据源到 store。例如，同步 websocket 数据源到 store（下面是个大概例子，实际上 `createWebSocketPlugin` 方法可以有更多选项来完成复杂任务）：
 
 ``` js
 export default function createWebSocketPlugin (socket) {
@@ -90,9 +90,9 @@ const store = createStore({
 Vuex 自带一个日志插件用于一般的调试:
 
 ``` js
-import createLogger from 'vuex/dist/logger'
+import { createLogger } from 'vuex'
 
-const store = new Vuex.Store({
+const store = createStore({
   plugins: [createLogger()]
 })
 ```

docs/zh/guide/testing.md

@@ -119,7 +119,7 @@ const testAction = (action, args, state, expectedMutations, done) => {
 
 describe('actions', () => {
   it('getAllProducts', done => {
-    testAction(actions.getAllProducts, [], {}, [
+    testAction(actions.getAllProducts, null, {}, [
       { type: 'REQUEST_PRODUCTS' },
       { type: 'RECEIVE_PRODUCTS', payload: { /* mocked response */ } }
     ], done)