Improved docs.

CHANGELOG.md

@@ -3,7 +3,7 @@ an <a href="https://github.com/marcglasberg/SameAppDifferentTech/blob/main/Mobil
 Async Redux App Example Repository</a> in GitHub for a full-fledged example with a complete app
 showcasing the fundamentals and best practices described in the AsyncRedux README.md file._
 
-# 22.4.3
+# 22.4.5
 
 * For those who use `flutter_hooks`, you can now use the
   new https://pub.dev/packages/flutter_hooks_async_redux package

lib/src/redux_action.dart

@@ -84,24 +84,36 @@ abstract class ReduxAction<St> {
   /// The action may be sync or async.
   ///
   /// ```dart
-  /// dispatch(MyAction());
+  /// store.dispatch(MyAction());
   /// ```
+  /// If you pass the [notify] parameter as `false`, widgets will not necessarily rebuild because
+  /// of this action, even if it changes the state.
   ///
   /// Method [dispatch] is of type [Dispatch].
   ///
   /// See also:
   /// - [dispatchSync] which dispatches sync actions, and throws if the action is async.
   /// - [dispatchAndWait] which dispatches both sync and async actions, and returns a Future.
+  ///
   Dispatch<St> get dispatch => _store.dispatch;
 
   /// Dispatches the action, applying its reducer, and possibly changing the store state.
   /// However, if the action is ASYNC, it will throw a [StoreException].
   ///
-  /// Method [dispatchSync] is of type [DispatchSync].
+  /// If you pass the [notify] parameter as `false`, widgets will not necessarily rebuild because
+  /// of this action, even if it changes the state.
+  ///
+  /// Method [dispatchSync] is of type [DispatchSync]. It returns `ActionStatus`,
+  /// which means you can also get the final status of the action:
+  ///
+  /// ```dart
+  /// var status = store.dispatchSync(MyAction());
+  /// ```
   ///
   /// See also:
   /// - [dispatch] which dispatches both sync and async actions.
   /// - [dispatchAndWait] which dispatches both sync and async actions, and returns a Future.
+  ///
   DispatchSync<St> get dispatchSync => _store.dispatchSync;
 
   @Deprecated("Use `dispatchAndWait` instead. This will be removed.")
@@ -112,10 +124,13 @@ abstract class ReduxAction<St> {
   /// the action finishes.
   ///
   /// ```dart
-  /// await dispatchAndWait(DoThisFirstAction());
-  /// dispatch(DoThisSecondAction());
+  /// await store.dispatchAndWait(DoThisFirstAction());
+  /// store.dispatch(DoThisSecondAction());
   /// ```
   ///
+  /// If you pass the [notify] parameter as `false`, widgets will not necessarily rebuild because
+  /// of this action, even if it changes the state.
+  ///
   /// Note: While the state change from the action's reducer will have been applied when the
   /// Future resolves, other independent processes that the action may have started may still
   /// be in progress.
@@ -124,12 +139,13 @@ abstract class ReduxAction<St> {
   /// which means you can also get the final status of the action after you `await` it:
   ///
   /// ```dart
-  /// var status = await dispatchAndWait(MyAction());
+  /// var status = await store.dispatchAndWait(MyAction());
   /// ```
   ///
   /// See also:
   /// - [dispatch] which dispatches both sync and async actions.
   /// - [dispatchSync] which dispatches sync actions, and throws if the action is async.
+  ///
   DispatchAndWait<St> get dispatchAndWait => _store.dispatchAndWait;
 
   /// This is an optional method that may be overridden to run during action

lib/src/store.dart

@@ -1090,18 +1090,43 @@ class Store<St> {
   /// ```dart
   /// store.dispatch(MyAction());
   /// ```
+  /// If you pass the [notify] parameter as `false`, widgets will not necessarily rebuild because
+  /// of this action, even if it changes the state.
   ///
   /// Method [dispatch] is of type [Dispatch].
   ///
   /// See also:
   /// - [dispatchSync] which dispatches sync actions, and throws if the action is async.
   /// - [dispatchAndWait] which dispatches both sync and async actions, and returns a Future.
+  ///
   FutureOr<ActionStatus> dispatch(ReduxAction<St> action, {bool notify = true}) =>
       _dispatch(action, notify: notify);
 
-  @Deprecated("Use `dispatchAndWait` instead. This will be removed.")
-  Future<ActionStatus> dispatchAsync(ReduxAction<St> action, {bool notify = true}) =>
-      dispatchAndWait(action, notify: notify);
+  /// Dispatches the action, applying its reducer, and possibly changing the store state.
+  /// However, if the action is ASYNC, it will throw a [StoreException].
+  ///
+  /// If you pass the [notify] parameter as `false`, widgets will not necessarily rebuild because
+  /// of this action, even if it changes the state.
+  ///
+  /// Method [dispatchSync] is of type [DispatchSync]. It returns `ActionStatus`,
+  /// which means you can also get the final status of the action:
+  ///
+  /// ```dart
+  /// var status = store.dispatchSync(MyAction());
+  /// ```
+  ///
+  /// See also:
+  /// - [dispatch] which dispatches both sync and async actions.
+  /// - [dispatchAndWait] which dispatches both sync and async actions, and returns a Future.
+  ///
+  ActionStatus dispatchSync(ReduxAction<St> action, {bool notify = true}) {
+    if (!action.isSync()) {
+      throw StoreException(
+          "Can't dispatchSync(${action.runtimeType}) because ${action.runtimeType} is async.");
+    }
+
+    return _dispatch(action, notify: notify) as ActionStatus;
+  }
 
   /// Dispatches the action, applying its reducer, and possibly changing the store state.
   /// The action may be sync or async. In both cases, it returns a [Future] that resolves when
@@ -1112,6 +1137,9 @@ class Store<St> {
   /// store.dispatch(DoThisSecondAction());
   /// ```
   ///
+  /// If you pass the [notify] parameter as `false`, widgets will not necessarily rebuild because
+  /// of this action, even if it changes the state.
+  ///
   /// Note: While the state change from the action's reducer will have been applied when the
   /// Future resolves, other independent processes that the action may have started may still
   /// be in progress.
@@ -1126,25 +1154,13 @@ class Store<St> {
   /// See also:
   /// - [dispatch] which dispatches both sync and async actions.
   /// - [dispatchSync] which dispatches sync actions, and throws if the action is async.
+  ///
   Future<ActionStatus> dispatchAndWait(ReduxAction<St> action, {bool notify = true}) =>
       Future.value(_dispatch(action, notify: notify));
 
-  /// Dispatches the action, applying its reducer, and possibly changing the store state.
-  /// However, if the action is ASYNC, it will throw a [StoreException].
-  ///
-  /// Method [dispatchSync] is of type [DispatchSync].
-  ///
-  /// See also:
-  /// - [dispatch] which dispatches both sync and async actions.
-  /// - [dispatchAndWait] which dispatches both sync and async actions, and returns a Future.
-  ActionStatus dispatchSync(ReduxAction<St> action, {bool notify = true}) {
-    if (!action.isSync()) {
-      throw StoreException(
-          "Can't dispatchSync(${action.runtimeType}) because ${action.runtimeType} is async.");
-    }
-
-    return _dispatch(action, notify: notify) as ActionStatus;
-  }
+  @Deprecated("Use `dispatchAndWait` instead. This will be removed.")
+  Future<ActionStatus> dispatchAsync(ReduxAction<St> action, {bool notify = true}) =>
+      dispatchAndWait(action, notify: notify);
 
   FutureOr<ActionStatus> _dispatch(ReduxAction<St> action, {required bool notify}) {
     //