From 0e60aa761eae90d12315f543db904ab9770b104f Mon Sep 17 00:00:00 2001
From: Arya Emami <aryaemami59@yahoo.com>
Date: Fri, 5 Jan 2024 12:58:58 -0600
Subject: [PATCH] Add JSDocs for `useDispatch`

---
 src/hooks/useDispatch.ts | 47 ++++++++++++++++++++++++++++++++++++----
 test/typetests/hooks.tsx |  1 -
 2 files changed, 43 insertions(+), 5 deletions(-)

diff --git a/src/hooks/useDispatch.ts b/src/hooks/useDispatch.ts
index e72c6f758..f8c9737e3 100644
--- a/src/hooks/useDispatch.ts
+++ b/src/hooks/useDispatch.ts
@@ -5,11 +5,45 @@ import type { ReactReduxContextValue } from '../components/Context'
 import { ReactReduxContext } from '../components/Context'
 import { createStoreHook, useStore as useDefaultStore } from './useStore'
 
+/**
+ * Represents a custom hook that provides a dispatch function
+ * from the Redux store.
+ *
+ * @template DispatchType - The specific type of the dispatch function.
+ *
+ * @since 9.1.0
+ * @public
+ */
 export interface UseDispatch<
   DispatchType extends Dispatch<UnknownAction> = Dispatch<UnknownAction>
 > {
+  /**
+   * Returns the dispatch function from the Redux store.
+   *
+   * @returns The dispatch function from the Redux store.
+   *
+   * @template AppDispatch - The specific type of the dispatch function.
+   */
   <AppDispatch extends DispatchType = DispatchType>(): AppDispatch
 
+  /**
+   * Creates a "pre-typed" version of {@linkcode useDispatch useDispatch}
+   * where the type of the `dispatch` function is predefined.
+   *
+   * This allows you to set the `dispatch` type once, eliminating the need to
+   * specify it with every {@linkcode useDispatch useDispatch} call.
+   *
+   * @returns A pre-typed `useDispatch` with the dispatch type already defined.
+   *
+   * @example
+   * ```ts
+   * const useAppDispatch = useDispatch.withTypes<AppDispatch>()
+   * ```
+   *
+   * @template OverrideDispatchType - The specific type of the dispatch function.
+   *
+   * @since 9.1.0
+   */
   withTypes: <
     OverrideDispatchType extends DispatchType
   >() => UseDispatch<OverrideDispatchType>
@@ -22,10 +56,15 @@ export interface UseDispatch<
  * @returns {Function} A `useDispatch` hook bound to the specified context.
  */
 export function createDispatchHook<
-  S = unknown,
-  A extends Action = UnknownAction
+  StateType = unknown,
+  ActionType extends Action = UnknownAction
+>(
   // @ts-ignore
->(context?: Context<ReactReduxContextValue<S, A> | null> = ReactReduxContext) {
+  context?: Context<ReactReduxContextValue<
+    StateType,
+    ActionType
+  > | null> = ReactReduxContext
+) {
   const useStore =
     context === ReactReduxContext ? useDefaultStore : createStoreHook(context)
 
@@ -38,7 +77,7 @@ export function createDispatchHook<
     withTypes: () => useDispatch,
   })
 
-  return useDispatch as UseDispatch<Dispatch<A>>
+  return useDispatch as UseDispatch<Dispatch<ActionType>>
 }
 
 /**
diff --git a/test/typetests/hooks.tsx b/test/typetests/hooks.tsx
index 7767d965c..dc8bddf86 100644
--- a/test/typetests/hooks.tsx
+++ b/test/typetests/hooks.tsx
@@ -84,7 +84,6 @@ function testShallowEqual() {
   )
   expectExactType<string>(selected1)
 
-  // const useAppSelector: UseSelector<TestState> = useSelector
   const useAppSelector = useSelector.withTypes<TestState>()
 
   const selected2 = useAppSelector((state) => state.stateProp, shallowEqual)