Review resolutions

wgao19 · wgao19 · commit 9a14bef019c7 · 2018-10-29T01:20:11.000+08:00
diff --git a/docs/using-react-redux/connect-dispatching-actions-with-mapDispatchToProps.md b/docs/using-react-redux/connect-dispatching-actions-with-mapDispatchToProps.md
@@ -2,7 +2,7 @@
 id: connect-dispatching-actions-with-mapDispatchToProps
 title: Connect: Dispatching Actions with mapDispatchToProps
 hide_title: true
-sidebar_label: Connect: Dispatching Actions with mapStateToProps
+sidebar_label: Connect: Dispatching Actions with mapDispatchToProps
 ---
 
 # Connect: Dispatching Actions with `mapDispatchToProps`
@@ -18,9 +18,9 @@ React-Redux gives you two ways to let components dispatch actions:
 - By default, a connected component receives `props.dispatch` and can dispatch actions itself.
 - `connect` can accept an argument called `mapDispatchToProps`, which lets you create functions that dispatch when called, and pass those functions as props to your component.
 
-The `mapDispatchToProps` functions are normally referred to as `mapDispatch` for short, and of course the actual variable name doesn’t matter in real code.
+The `mapDispatchToProps` functions are normally referred to as `mapDispatch` for short, but the actual variable name used can be whatever you want.
 
-## With or Without `mapDispatchToProps`
+## Approaches for Dispatching
 
 ### Default: `dispatch` as a Prop
 
@@ -53,23 +53,22 @@ function Counter({ count, dispatch }) {
 }
 ```
 
-### Providing A `mapDispatchToProps`
+### Providing A `mapDispatchToProps` Parameter
 
 Providing a `mapDispatchToProps` allows you to specify which actions your component might need to dispatch. It lets you provide action dispatching functions as props. Therefore, instead of calling `props.dispatch(() => increment())`, you may call `props.increment()` directly. There are a few reasons why you might want to do that.
 
 #### More Declarative
 
 First, encapsulating the dispatch logic into function makes the implementation more declarative.
-Dispatching an action and let the Redux store handle the data flow is _how to_ implement the feature, it is not _what_ it does.
-Therefore, instead of saying:
+Dispatching an action and letting the Redux store handle the data flow is _how to_ implement the behavior, rather than _what_ it does.
+
+A good example would be dispatching an action when a button is clicked. Connecting the button directly probably doesn't make sense conceptually, and neither does having the button reference `dispatch`.
 
 ```js
+// button needs to be aware of "dispatch"
 <button onClick={() => dispatch({ type: "SOMETHING" })} />
-```
-
-you may prefer saying:
 
-```js
+// button unaware of "dispatch",
 <button onClick={doSomething} />
 ```
 
@@ -78,7 +77,20 @@ Therefore, **if you define your own `mapDispatchToProps`, the connected componen
 
 #### Pass Down Action Dispatching Logic to ( Unconnected ) Child Components
 
-Furthermore, you also gain the freedom of passing down the action dispatching functions to child ( likely unconnected ) components. Now, both the connected component and its descendant need not be aware of `dispatch`, while performing their communications with the Redux store.
+In addition, you also gain the ability to pass down the action dispatching functions to child ( likely unconnected ) components.
+This allows more components to dispatch actions, while keeping them "unaware" of Redux.
+
+```jsx
+// pass down toggleTodo to child component
+// making Todo able to dispatch the toggleTodo action
+const TodoList = ({ todos, toggleTodo }) => (
+  <div>
+    {todos.map(todo => (
+      <Todo todo={todo} onClick={toggleTodo} />
+    ))}
+  </div>
+);
+```
 
 This is what React-Redux’s `connect` does — it encapsulates the logic of talking to the Redux store and lets you not worry about it. And this is what you should totally make full use of in your implementation.
 
@@ -87,9 +99,9 @@ This is what React-Redux’s `connect` does — it encapsulates the logic of tal
 The `mapDispatchToProps` parameter can be of two forms. While the function form allows more customization, the object form is easy to use.
 
 - **Function form**: Allows more customization, gains access to `dispatch` and optionally `ownProps`
-- **Object short hand form**: More declarative and easier to use
+- **Object shorthand form**: More declarative and easier to use
 
-⭐ We recommend using the object form of `mapDispatchToProps` unless you specifically need to customize dispatching behavior in some way.
+> ⭐ **Note:** We recommend using the object form of `mapDispatchToProps` unless you specifically need to customize dispatching behavior in some way.
 
 ## Defining `mapDispatchToProps` As A Function
 
@@ -104,7 +116,8 @@ You may use this chance to write customized functions to be called by your conne
 
 **`dispatch`**
 
-The `mapDispatchToProps` function will be called with `dispatch` as the argument. You may use this param to wrap around the actions you wish to dispatch, or the action creators that return the actions.
+The `mapDispatchToProps` function will be called with `dispatch` as the first argument.
+You will normally make use of this by returning new functions that call `dispatch()` inside themselves, and either pass in a plain action object directly or pass in the result of an action creator.
 
 ```js
 const mapDispatchToProps = dispatch => {
@@ -117,7 +130,7 @@ const mapDispatchToProps = dispatch => {
 };
 ```
 
-You may take this chance to forward arguments to your action creators:
+You will also likely want to forward arguments to your action creators:
 
 ```js
 const mapDispatchToProps = dispatch => {
@@ -152,7 +165,7 @@ const mapDispatchToProps = (dispatch, ownProps) => {
 
 Your `mapDispatchToProps` function should return a plain object:
 
-- Each field in the object should be a function, calling which should automatically dispatch the action
+- Each field in the object will become a separate prop for your own component, and the value should normally be a function that dispatches an action when called.
 - If you use action creators ( as oppose to plain object actions ) inside `dispatch`, it is a convention to simply name the field key the same name as the action creator:
 
 ```js
@@ -198,6 +211,8 @@ Wrapping these functions by hand is tedious, so Redux provides a function to sim
 1. A **`function`** (an action creator) or an **`object`** (each field an action creator)
 2. `dispatch`
 
+The wrapper functions generated by `bindActionCreators` will automatically forward all of their arguments, so you don't need to do that by hand.
+
 ```js
 import { bindActionCreators } from "redux";
 
@@ -206,23 +221,19 @@ const decrement = () => ({ type: "DECREMENT" });
 const reset = () => ({ type: "RESET" });
 
 // binding an action creator
-// returns () => dispatch(increment())
-bindActionCreators(increment, dispatch);
+// returns (...args) => dispatch(increment(...args))
+const boundIncrement = bindActionCreators(increment, dispatch);
 
 // binding an object full of action creators
-bindActionCreators(
-  {
-    increment,
-    decrement,
-    reset
-  },
+const boundActionCreators = bindActionCreators(
+  { increment, decrement, reset },
   dispatch
 );
 // returns
 // {
-//   increment: () => dispatch(increment()),
-//   decrement: () => dispatch(decrement()),
-//   reset: () => dispatch(reset()),
+//   increment: (...args) => dispatch(increment(...args)),
+//   decrement: (...args) => dispatch(decrement(...args)),
+//   reset: (...args) => dispatch(reset(...args)),
 // }
 ```
 
@@ -233,14 +244,7 @@ import { bindActionCreators } from "redux";
 // ...
 
 function mapDispatchToProps(dispatch) {
-  return bindActionCreators(
-    {
-      increment, // () => dispatch(increment())
-      decrement, // () => dispatch(decrement())
-      reset // () => dispatch(reset())
-    },
-    dispatch
-  );
+  return bindActionCreators({ increment, decrement, reset }, dispatch);
 }
 
 // component receives props.increment, props.decrement, props.reset
@@ -252,7 +256,7 @@ connect(
 
 ### Manually Injecting `dispatch`
 
-Since the `mapDispatchToProps` argument is supplied, the component will no longer receive the default `dispatch`. You may bring it back by adding it manually to the return of your `mapDispatchToProps`, although most of the time you shouldn’t need to do this:
+If the `mapDispatchToProps` argument is supplied, the component will no longer receive the default `dispatch`. You may bring it back by adding it manually to the return of your `mapDispatchToProps`, although most of the time you shouldn’t need to do this:
 
 ```js
 import { bindActionCreators } from "redux";
@@ -261,14 +265,7 @@ import { bindActionCreators } from "redux";
 function mapDispatchToProps(dispatch) {
   return {
     dispatch,
-    ...bindActionCreators(
-      {
-        increment,
-        decrement,
-        reset
-      },
-      dispatch
-    )
+    ...bindActionCreators({ increment, decrement, reset }, dispatch)
   };
 }
 ```
@@ -316,7 +313,7 @@ export default connect(mapState, actionCreators)(Counter);
 
 // or
 export default connect(
-  null,
+  mapState,
   { increment, decrement, reset }
 )(Counter);
 ```
@@ -369,14 +366,7 @@ import { bindActionCreators } from "redux";
 function mapDispatchToProps(dispatch) {
   return {
     dispatch,
-    ...bindActionCreators(
-      {
-        increment,
-        decrement,
-        reset
-      },
-      dispatch
-    )
+    ...bindActionCreators({ increment, decrement, reset }, dispatch)
   };
 }
 ```
@@ -387,7 +377,7 @@ There are discussions regarding whether to provide `dispatch` to your components
 
 ### Can I `mapDispatchToProps` without `mapStateToProps` in Redux?
 
-Yes. You can skip the first parameter by passing `undefined` or `null`. Your component will not subscribe to the store, and gain dispatch props defined by `mapStateToProps`.
+Yes. You can skip the first parameter by passing `undefined` or `null`. Your component will not subscribe to the store, and will still receive the dispatch props defined by `mapStateToProps`.
 
 ```js
 connect(
@@ -398,7 +388,7 @@ connect(
 
 ### Can I call `store.dispatch`?
 
-It is an anti-pattern to use `store.dispatch` which you may retrieve from the `store` in context. As explained in [Redux's FAQ on store setup](https://redux.js.org/faq/storesetup#can-or-should-i-create-multiple-stores-can-i-import-my-store-directly-and-use-it-in-components-myself), any direct access of the store in a component is not recommended, whether it be via direct import or from context. Let React-Redux’s `connect` handle the access to the store, and use the `dispatch` it passes to the props to dispatch actions.
+It's an anti-pattern to interact with the store directly in a React component, whether it's an explicit import of the store or accessing it via context (see the [Redux FAQ entry on store setup](https://redux.js.org/faq/storesetup#can-or-should-i-create-multiple-stores-can-i-import-my-store-directly-and-use-it-in-components-myself) for more details). Let React-Redux’s `connect` handle the access to the store, and use the `dispatch` it passes to the props to dispatch actions.
 
 ## Links and References
 
