From f2cfe29e622278e6138595967d8356d5d1346b33 Mon Sep 17 00:00:00 2001
From: Jonathan Ziller <jonathan.ziller@gmail.com>
Date: Tue, 23 Apr 2019 20:17:19 +0200
Subject: [PATCH] use proper example code tag in hooks JSDoc comments (#1257)

* use proper example code tag in hooks JSDoc comments

* fix mistake in `useActions` hook example code

* remove TypeScript annotations from example code and adjust `useReduxContext` hook to also use @example JSDoc tag
---
 src/hooks/useActions.js      | 84 ++++++++++++++++++------------------
 src/hooks/useDispatch.js     | 32 +++++++-------
 src/hooks/useRedux.js        | 53 ++++++++++++-----------
 src/hooks/useReduxContext.js | 20 ++++-----
 src/hooks/useSelector.js     | 23 +++++-----
 src/hooks/useStore.js        | 20 ++++-----
 6 files changed, 113 insertions(+), 119 deletions(-)

diff --git a/src/hooks/useActions.js b/src/hooks/useActions.js
index 4c924f509..9321280cf 100644
--- a/src/hooks/useActions.js
+++ b/src/hooks/useActions.js
@@ -6,59 +6,57 @@ import { useMemo } from 'react'
 /**
  * A hook to bind action creators to the redux store's `dispatch` function
  * similar to how redux's `bindActionCreators` works.
- * 
+ *
  * Supports passing a single action creator, an array/tuple of action
  * creators, or an object of action creators.
- * 
+ *
  * Any arguments passed to the created callbacks are passed through to
- * the your functions.
- * 
+ * your functions.
+ *
  * This hook takes a dependencies array as an optional second argument,
  * which when passed ensures referential stability of the created callbacks.
- * 
+ *
  * @param {Function|Function[]|Object.<string, Function>} actions the action creators to bind
  * @param {any[]} deps (optional) dependencies array to control referential stability
- * 
+ *
  * @returns {Function|Function[]|Object.<string, Function>} callback(s) bound to store's `dispatch` function
  *
- * Usage:
+ * @example
  *
-```jsx
-import React from 'react'
-import { useActions } from 'react-redux'
-
-const increaseCounter = ({ amount }) => ({
-  type: 'increase-counter',
-  amount,
-})
-
-export const CounterComponent = ({ value }) => {
-  // supports passing an object of action creators
-  const { increaseCounterByOne, increaseCounterByTwo } = useActions({
-    increaseCounterByOne: () => increaseCounter(1),
-    increaseCounterByTwo: () => increaseCounter(2),
-  }, [])
-
-  // supports passing an array/tuple of action creators
-  const [increaseCounterByThree, increaseCounterByFour] = useActions([
-    () => increaseCounter(3),
-    () => increaseCounter(4),
-  ], [])
-
-  // supports passing a single action creator
-  const increaseCounterBy5 = useActions(() => increaseCounter(5), [])
-
-  // passes through any arguments to the callback
-  const increaseCounterByX = useActions(x => increaseCounter(x), [])
-
-  return (
-    <div>
-      <span>{value}</span>
-      <button onClick={increaseCounterByOne}>Increase counter by 1</button>
-    </div>
-  )
-}
-```
+ * import React from 'react'
+ * import { useActions } from 'react-redux'
+ *
+ * const increaseCounter = amount => ({
+ *   type: 'increase-counter',
+ *   amount,
+ * })
+ *
+ * export const CounterComponent = ({ value }) => {
+ *   // supports passing an object of action creators
+ *   const { increaseCounterByOne, increaseCounterByTwo } = useActions({
+ *     increaseCounterByOne: () => increaseCounter(1),
+ *     increaseCounterByTwo: () => increaseCounter(2),
+ *   }, [])
+ *
+ *   // supports passing an array/tuple of action creators
+ *   const [increaseCounterByThree, increaseCounterByFour] = useActions([
+ *     () => increaseCounter(3),
+ *     () => increaseCounter(4),
+ *   ], [])
+ *
+ *   // supports passing a single action creator
+ *   const increaseCounterBy5 = useActions(() => increaseCounter(5), [])
+ *
+ *   // passes through any arguments to the callback
+ *   const increaseCounterByX = useActions(x => increaseCounter(x), [])
+ *
+ *   return (
+ *     <div>
+ *       <span>{value}</span>
+ *       <button onClick={increaseCounterByOne}>Increase counter by 1</button>
+ *     </div>
+ *   )
+ * }
  */
 export function useActions(actions, deps) {
   invariant(actions, `You must pass actions to useActions`)
diff --git a/src/hooks/useDispatch.js b/src/hooks/useDispatch.js
index 7331ea351..cdef99c9b 100644
--- a/src/hooks/useDispatch.js
+++ b/src/hooks/useDispatch.js
@@ -4,26 +4,24 @@ import { useStore } from './useStore'
  * A hook to access the redux `dispatch` function. Note that in most cases where you
  * might want to use this hook it is recommended to use `useActions` instead to bind
  * action creators to the `dispatch` function.
- * 
+ *
  * @returns {any} redux store's `dispatch` function
  *
- * Usage:
+ * @example
  *
-```jsx
-import React, { useCallback } from 'react'
-import { useReduxDispatch } from 'react-redux'
-
-export const CounterComponent = ({ value }) => {
-  const dispatch = useDispatch()
-  const increaseCounter = useCallback(() => dispatch({ type: 'increase-counter' }), [])
-  return (
-    <div>
-      <span>{value}</span>
-      <button onClick={increaseCounter}>Increase counter</button>
-    </div>
-  )
-}
-```
+ * import React, { useCallback } from 'react'
+ * import { useReduxDispatch } from 'react-redux'
+ *
+ * export const CounterComponent = ({ value }) => {
+ *   const dispatch = useDispatch()
+ *   const increaseCounter = useCallback(() => dispatch({ type: 'increase-counter' }), [])
+ *   return (
+ *     <div>
+ *       <span>{value}</span>
+ *       <button onClick={increaseCounter}>Increase counter</button>
+ *     </div>
+ *   )
+ * }
  */
 export function useDispatch() {
   const store = useStore()
diff --git a/src/hooks/useRedux.js b/src/hooks/useRedux.js
index 58f7f4ee9..293abc8c3 100644
--- a/src/hooks/useRedux.js
+++ b/src/hooks/useRedux.js
@@ -2,38 +2,41 @@ import { useSelector } from './useSelector'
 import { useActions } from './useActions'
 
 /**
- * A hook to access the redux store's state and to bind action creators to 
+ * A hook to access the redux store's state and to bind action creators to
  * the store's dispatch function. In essence, this hook is a combination of
  * `useSelector` and `useActions`.
- * 
+ *
+ * Note that this hook does currently not allow to pass a dependencies array,
+ * so the passed selector and any created callbacks are not memoized. If you
+ * require memoization, please use `useActions` and `useSelector`.
+ *
  * @param {Function} selector the selector function
  * @param {Function|Function[]|Object.<string, Function>} actions the action creators to bind
- * 
+ *
  * @returns {[any, any]} a tuple of the selected state and the bound action creators
  *
- * Usage:
+ * @example
  *
-```jsx
-import React from 'react'
-import { useRedux } from 'react-redux'
-
-export const CounterComponent = () => {
-  const [counter, { inc1, inc }] = useRedux(state => state.counter, {
-    inc1: () => ({ type: 'inc1' }),
-    inc: amount => ({ type: 'inc', amount }),
-  })
-
-  return (
-    <>
-      <div>
-        {counter}
-      </div>
-      <button onClick={inc1}>Increment by 1</button>
-      <button onClick={() => inc(5)}>Increment by 5</button>
-    </>
-  )
-}
-```
+ * import React from 'react'
+ * import { useRedux } from 'react-redux'
+ * import { RootState } from './store'
+ *
+ * export const CounterComponent = () => {
+ *   const [counter, { inc1, inc }] = useRedux(state => state.counter, {
+ *     inc1: () => ({ type: 'inc1' }),
+ *     inc: amount => ({ type: 'inc', amount }),
+ *   })
+ *
+ *   return (
+ *     <>
+ *       <div>
+ *         {counter}
+ *       </div>
+ *       <button onClick={inc1}>Increment by 1</button>
+ *       <button onClick={() => inc(5)}>Increment by 5</button>
+ *     </>
+ *   )
+ * }
  */
 export function useRedux(selector, actions) {
   return [useSelector(selector), useActions(actions)]
diff --git a/src/hooks/useReduxContext.js b/src/hooks/useReduxContext.js
index e580b0eeb..903a11c44 100644
--- a/src/hooks/useReduxContext.js
+++ b/src/hooks/useReduxContext.js
@@ -5,20 +5,18 @@ import { ReactReduxContext } from '../components/Context'
 /**
  * A hook to access the value of the `ReactReduxContext`. This is a low-level
  * hook that you should usually not need to call directly.
- * 
+ *
  * @returns {any} the value of the `ReactReduxContext`
  *
- * Usage:
+ * @example
  *
-```jsx
-import React from 'react'
-import { useReduxContext } from 'react-redux'
-
-export const CounterComponent = ({ value }) => {
-  const { store } = useReduxContext()
-  return <div>{store.getState()}</div>
-}
-```
+ * import React from 'react'
+ * import { useReduxContext } from 'react-redux'
+ *
+ * export const CounterComponent = ({ value }) => {
+ *   const { store } = useReduxContext()
+ *   return <div>{store.getState()}</div>
+ * }
  */
 export function useReduxContext() {
   const contextValue = useContext(ReactReduxContext)
diff --git a/src/hooks/useSelector.js b/src/hooks/useSelector.js
index 70fb70934..83e1666f9 100644
--- a/src/hooks/useSelector.js
+++ b/src/hooks/useSelector.js
@@ -22,24 +22,23 @@ const useIsomorphicLayoutEffect =
  * This hook takes a dependencies array as an optional second argument,
  * which when passed ensures referential stability of the selector (this is primarily
  * useful if you provide a selector that memoizes values).
- * 
+ *
  * @param {Function} selector the selector function
  * @param {any[]} deps (optional) dependencies array to control referential stability
  * of the selector
- * 
+ *
  * @returns {any} the selected state
  *
- * Usage:
+ * @example
  *
-```jsx
-import React from 'react'
-import { useSelector } from 'react-redux'
-
-export const CounterComponent = () => {
-  const counter = useSelector(state => state.counter)
-  return <div>{counter}</div>
-}
-```
+ * import React from 'react'
+ * import { useSelector } from 'react-redux'
+ * import { RootState } from './store'
+ *
+ * export const CounterComponent = () => {
+ *   const counter = useSelector(state => state.counter, [])
+ *   return <div>{counter}</div>
+ * }
  */
 export function useSelector(selector, deps) {
   invariant(selector, `You must pass a selector to useSelectors`)
diff --git a/src/hooks/useStore.js b/src/hooks/useStore.js
index ff19882d2..16cca17a4 100644
--- a/src/hooks/useStore.js
+++ b/src/hooks/useStore.js
@@ -2,20 +2,18 @@ import { useReduxContext } from './useReduxContext'
 
 /**
  * A hook to access the redux store.
- * 
+ *
  * @returns {any} the redux store
  *
- * Usage:
+ * @example
  *
-```jsx
-import React from 'react'
-import { useStore } from 'react-redux'
-
-export const CounterComponent = ({ value }) => {
-  const store = useStore()
-  return <div>{store.getState()}</div>
-}
-```
+ * import React from 'react'
+ * import { useStore } from 'react-redux'
+ *
+ * export const ExampleComponent = () => {
+ *   const store = useStore()
+ *   return <div>{store.getState()}</div>
+ * }
  */
 export function useStore() {
   const { store } = useReduxContext()