Update READMEs and comments within code for readability

Correct spelling errors.
Remove commented-out code.

README.md

@@ -8,7 +8,7 @@
 </p>
 
 <p align="justify">
-`states_rebuilder` is Flutter state management combined with a dependency injection solution and an integrated router to get the best state management experience and speed up your development.
+`states_rebuilder` is Flutter state management combined with a dependency injection solution and an integrated router to provide the best state management experience, speeding up your development as well.
 </p>
 
 
@@ -22,7 +22,7 @@
  -->
 
 # Contributing
-There are multiple ways and places you can contribute to make this package nicer, if you are wondering how to start please post an issue and we're here to help facilitate that.
+There are multiple ways and places you can contribute to make this package nicer. If you are wondering how to start please post an issue and we're here to help facilitate that.
 
   - Asking question, leaving suggestion
   - Code commits and pull requests
@@ -36,11 +36,11 @@ It is a feature-rich state management sulution:
 ## Performance
   - Predictable and controllable
   - Support for immutable / mutable state
-  - Strictly rebuild control
+  - Precise rebuild control
 
 ## Code Clean
   - Separation of UI & business logic
-  - Coding business logic in pure Dart.
+  - Coding of business logic in pure Dart.
   - Zero Boilerplate without code-generation 
 
 ## User Friendly
@@ -52,14 +52,14 @@ It is a feature-rich state management sulution:
     - Theme, multi-langs
     - Navigation, show dialogs without `BuildContext`
 
-## Effective Production
+## Efficient Productivity
   - CREATE, READ, UPDATE, and DELETE (CRUD) from rest-API or database
   - User authentication and authorization
   - App themes management
   - Internalization and localization
 
 ## Maintainable
-  - Easy to test, mock the dependencies
+  - Easy to test and mock dependencies
   - State tracker middleware
   - Built-in debugging print function
   - Capable for complex Apps

examples/ex001_00_sync_global_and_local_state/README.md

@@ -67,13 +67,13 @@ In this first set of examples, you will learn how to work with global and local
 
 ### Intermediate Level :sunglasses:
 
- - [09: State Persistence - Primitives](https://github.com/GIfatahTH/states_rebuilder/blob/dev/examples/ex001_00_sync_global_and_local_state/lib/ex_012_00_state_persistance.dart)
+ - [09: State Persistence - Primitives](https://github.com/GIfatahTH/states_rebuilder/blob/dev/examples/ex001_00_sync_global_and_local_state/lib/ex_012_00_state_persistence.dart)
    <br />**Description:**
-  Example of state persistance of primitives using `SharedPreferences`.
+  Example of state persistence of primitives using `SharedPreferences`.
 
- - [10: State Persistence - List of Objects](https://github.com/GIfatahTH/states_rebuilder/blob/dev/examples/ex001_00_sync_global_and_local_state/lib/ex_013_00_state_persistance_List_of_Object.dart)
+ - [10: State Persistence - List of Objects](https://github.com/GIfatahTH/states_rebuilder/blob/dev/examples/ex001_00_sync_global_and_local_state/lib/ex_013_00_state_persistence_List_of_Object.dart)
    <br />**Description:**
-  Example of state persistance of list of objects using `Hive`.
+  Example of state persistence of list of objects using `Hive`.
 
  - [11: State Interceptor](https://github.com/GIfatahTH/states_rebuilder/blob/dev/examples/ex001_00_sync_global_and_local_state/lib/ex_014_00_state_interceptor.dart)
    <br />**Description:**
@@ -100,8 +100,8 @@ In this first set of examples, you will learn how to work with global and local
 [🔍 See more detailed information about state management API](https://github.com/GIfatahTH/states_rebuilder/wiki/home).
 
 
-## Question & Suggestion
-Please feel free to post an issue or PR, as always, your feedback makes this library become better and better.
+## Questions & Suggestions
+Please feel free to post an issue or PR. As always, your feedback makes this library become better and better.
 
 
-This is the end this part. Take another step and see [here for more advanced async state mutation](./../ex002_00_async_global_and_local_state)
+This is the end this part. Take another step and see [here for more advanced async state mutation](./../ex002_00_async_global_and_local_state)

examples/ex001_00_sync_global_and_local_state/lib/ex_001_00_default_counter_app.dart

@@ -39,7 +39,7 @@ class MyHomePage extends ReactiveStatelessWidget {
   // static final _counter = RM.inject(() => 0);
 
   void _incrementCounter() {
-    // increment the state of the counter and emit nonfiction to listeners
+    // increment the state of the counter and emit a notification to listeners
     _counter.state++;
     // For more options use setState
     // _counter.setState((s) => s + 1);
@@ -65,8 +65,8 @@ class MyHomePage extends ReactiveStatelessWidget {
               // Get the state.
               //
               // As state is consumed inside the ReactiveStatelessWidget, the
-              // latter will listen to _counter state to rebuild when
-              // the _counter state emits notification
+              // following will listen to _counter state to rebuild when
+              // the _counter state emits a notification
               '${_counter.state}',
               style: Theme.of(context).textTheme.headline4,
             ),

examples/ex001_00_sync_global_and_local_state/lib/ex_002_00_default_counter_app.dart

@@ -2,7 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 
 /*
-* This is similar to the last example except that counter Text widget is extracted
+* This is similar to the last example except that the counter Text widget is extracted
 * to its own widget class.
 *
 */
@@ -59,7 +59,7 @@ class MyHomePage extends ReactiveStatelessWidget {
             // In this example, adding const modifier will prevent
             // CounterWidget from rebuild.
             //
-            // TODO: Try add const modifer and notice that it is not rebuilding.
+            // TODO: Try add const modifier and notice that it is not rebuilding.
             // ignore: prefer_const_constructors
             /*const*/ CounterWidget(),
           ],
@@ -86,11 +86,11 @@ class CounterWidget extends StatelessWidget {
       // As we consume the state here, the _counter will look up the widget tree
       // for any ReactiveStatelessWidget. The first it finds will be registered.
       //
-      // In this example, as MyHomePage is ReactiveStatelessWidget, it will be
+      // In this example, as MyHomePage is a ReactiveStatelessWidget, it will be
       // registered for rebuild.
       //
-      // When _counter emits a notification, MyHomePage will rebuild and as
-      // CounterWidget is a child of MyHomePage it will rebuild provided it is
+      // When _counter emits a notification, MyHomePage will rebuilt and as
+      // CounterWidget is a child of MyHomePage it will rebuilt provided it is
       // not instantiated with const modifier.
       //
       // For this widget to rebuild even if it is used with const modifier, this
@@ -102,9 +102,10 @@ class CounterWidget extends StatelessWidget {
 }
 
 /*
-* ReactiveStateless widget can resister to any state consumed in its child widget 
-* provided that the child widget is not lazily loaded as in ListView.builder items
+* ReactiveStatelessWidget can register any state consumed in its child widget
+* provided that the child widget is not lazily loaded as is the case with
+* ListView.builder items
 *
 * Child widget declared with const modifier can not register to parent 
 * ReactiveStatelessWidget
-*/
+*/

examples/ex001_00_sync_global_and_local_state/lib/ex_003_00_default_counter_app.dart

@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 /*
-* The use of OnReactive to limit the part of the widget to rebuild
+* Illustrates the use of OnReactive to limit the part of the widget to rebuild
 */
 
 final counter = 0.inj();
@@ -25,8 +25,8 @@ class MyApp extends StatelessWidget {
   }
 }
 
-// In this example, we can use ordinary StatelessWidget
-class MyHomePage extends ReactiveStatelessWidget {
+// In this example, we can use an ordinary StatelessWidget
+class MyHomePage extends StatelessWidget {
   const MyHomePage({Key? key, required this.title}) : super(key: key);
 
   final String title;
@@ -54,7 +54,8 @@ class MyHomePage extends ReactiveStatelessWidget {
               'You have pushed the button this many times:',
             ),
             // By wrapping the Text widget with OnReactive, the _counter state
-            // will register the OnReactive to rebuild and not the MyHomePage.
+            // will register the OnReactive to be rebuilt, and not
+            // the entire MyHomePage.
             OnReactive(
               () {
                 return Text(
@@ -78,4 +79,4 @@ class MyHomePage extends ReactiveStatelessWidget {
 /*
 * state when the widget is building, will look up the widget tree for the nearest 
 * ReactiveStateless widget to resister it.
-*/ 
+*/ 

examples/ex001_00_sync_global_and_local_state/lib/ex_004_00_default_counter_app.dart

@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 /*
-* The use of ObBuilder widget
+* Further example as to the use of the OnBuilder widget
 */
 
 final counter = RM.inject(() => 0);
@@ -25,6 +25,8 @@ class MyApp extends StatelessWidget {
   }
 }
 
+// You can use simple StatelessWidget when using the OnBuilder widget within
+// the build method
 // You can use simple StatelessWidget
 class MyHomePage extends ReactiveStatelessWidget {
   const MyHomePage({Key? key, required this.title}) : super(key: key);
@@ -52,8 +54,8 @@ class MyHomePage extends ReactiveStatelessWidget {
             const Text(
               'You have pushed the button this many times:',
             ),
-            // Use of ObBuilder listener widget.
-            // OnBuilder prevent child state from subscribing to parent
+            // Use of OnBuilder listener widget.
+            // OnBuilder prevents child state from subscribing to parent
             // ReactiveStatelessWidget
             OnBuilder(
               listenTo: counter,

examples/ex001_00_sync_global_and_local_state/lib/ex_005_00_model_view_view_model_counter_app.dart

@@ -8,7 +8,7 @@ void main() {
   runApp(const MyApp());
 }
 
-// Here lays all the business logic related to MyHomePage.
+// Here lies all the business logic related to MyHomePage.
 // This class can be named MyHomePageBloC, MyHomePageLogic or MyHomePageController
 //
 // This class is easily unit tested

examples/ex001_00_sync_global_and_local_state/lib/ex_006_00_disposing_state.dart

@@ -1,8 +1,8 @@
 import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 /*
-* states even if instantiated globally, have life cycle. This is an example of
-* state cleaning (disposing off)
+* States, even if instantiated globally, have a life cycle. This is an example of
+* state cleaning up after itself (disposing of itself)
 */
 
 void main() {
@@ -18,7 +18,7 @@ class CounterViewModel {
     () => 0,
     // See the console log
     debugPrintWhenNotifiedPreMessage: '_counter',
-    // TODO uncomment the next line to prevent _counter from disposing of
+    // TODO uncomment the next line to prevent _counter from disposing of itself
     // autoDisposeWhenNotUsed: false,
   );
   int get counter => _counter.state;
@@ -27,18 +27,18 @@ class CounterViewModel {
   }
 
   void dispose() {
-    // IF a state is set to not disposed of automatically (autoDisposeWhenNotUsed: false)
+    // If a state is set to not be disposed of automatically (autoDisposeWhenNotUsed: false),
     // it is a good practice to dispose of it manually
     _counter.dispose();
     //
-    // RM.disposeAll will dispose all injected state. It may be used in test
+    // RM.disposeAll will dispose all injected state. It may be used in tests
     // RM.disposeAll();
   }
 }
 
 // Although _counter is used only in a part of the app (in CounterView), it is
-// considered as global state. because only one instance of it is active at any
-// instant.
+// considered as global state, because only one instance of it is active at any
+// one time.
 final counterViewModel = CounterViewModel();
 
 class MyApp extends StatelessWidget {

examples/ex001_00_sync_global_and_local_state/lib/ex_008_00_local_state_the_right_way.dart

@@ -2,9 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 
 /*
-* Fixing the last example.
-*
-* The right way of injecting local states
+* Fixing the last example illustrating the right way of injecting local states
 */
 
 void main() {
@@ -28,8 +26,8 @@ class CounterViewModel {
 
 // Create a global instance of CounterViewModel
 //
-// This time we inject the CounterViewModel and postpone it initialization in
-// the UI
+// This time we inject the CounterViewModel and postpone its initialization
+// which is now handled by the UI
 final counterViewModel = RM.inject<CounterViewModel>(
   () => throw UnimplementedError(),
 );
@@ -64,7 +62,7 @@ class MyHomePage extends StatelessWidget {
         child: Column(
           mainAxisAlignment: MainAxisAlignment.center,
           children: [
-            // use of inherited method to scop local states
+            // use of inherited method to scope local states
             counterViewModel.inherited(
               stateOverride: () => CounterViewModel('1'),
               builder: (context) {

examples/ex001_00_sync_global_and_local_state/lib/ex_009_00_local_state_the_wrong_way.dart

@@ -2,8 +2,8 @@ import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 
 /*
-* Example of local states supposed to not interact with local states created in 
-* other route stack.
+* Example of local states erroneously interacting with local states created in
+* another route stack.
 *
 * This is the wrong version. see next example for the right one.
 */
@@ -28,7 +28,7 @@ class CounterViewModel {
 
 // Create a global instance of CounterViewModel
 //
-// As we need more the route to have its onw CounterView instance, this will not work
+// As we need more the route to have its own CounterView instance, this will not work
 //
 // See the next example of the correct injection of local state
 final counterViewModel = CounterViewModel('1');

examples/ex001_00_sync_global_and_local_state/lib/ex_010_00_local_state_the_right_way.dart

@@ -32,7 +32,7 @@ class CounterViewModel {
 // You can define one global instance of CounterViewModel.
 // and overrides it with local instances in the UI
 //
-// The global instance is obtained using counterViewModel.state,
+// The global instance is obtained using counterViewModel.state
 //
 // The local instance is obtained using counterViewModel.of(context) or,
 // counterViewModel(context).state

examples/ex001_00_sync_global_and_local_state/lib/ex_011_00_undo_and_redo_state.dart

@@ -2,7 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 
 /*
-* Example of undo redo immutable state
+* Example of undo redo of immutable state
 */
 
 void main() {

examples/ex001_00_sync_global_and_local_state/lib/ex_014_00_state_interceptor.dart

@@ -4,7 +4,7 @@ import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 
 /*
-* This example show how to use state interceptor
+* This example shows how to use state interceptor
 *
 * In the demo, depending on the weather conditions, we want to change the theme. 
 * We will use the state interceptor to optimize the theme modification call and 

examples/ex001_00_sync_global_and_local_state/lib/ex_015_00_side_effects.dart

@@ -0,0 +1 @@
+// todo

examples/ex001_00_sync_global_and_local_state/lib/ex_016_00_performance_optimization.dart

@@ -4,7 +4,8 @@ import 'package:flutter/material.dart';
 import 'package:states_rebuilder/states_rebuilder.dart';
 
 /*
-* This is a show case on how to limit the rebuild to the widget really need to
+* This is a show case on how to limit the rebuild of a widget
+* to that which only really is needed to
 * update its view.
 *
 * The example is inspired from provider_shopper in flutter examples repo
@@ -83,22 +84,22 @@ class _MyAppBar extends StatelessWidget {
 // Used for test
 final rebuiltItems = [];
 
-// For the sake of this example we make this widget ReactiveStatelessWidget.
+// For the sake of this example we make this widget a ReactiveStatelessWidget.
 class _MyListItem extends ReactiveStatelessWidget {
   final int index;
 
   const _MyListItem(this.index, {Key? key}) : super(key: key);
   // OnReactive and OnBuilder both have shouldRebuild parameter
   @override
   bool shouldRebuildWidget(SnapState oldSnap, SnapState currentSnap) {
-    // Check that the nonfiction is emitted from _selectedItems state
+    // Check that the notification is emitted from _selectedItems state
     if (currentSnap.type() == List<int>) {
       final oldItems = oldSnap.state as List<int>;
       final currentItems = currentSnap.state as List<int>;
       if (oldItems.contains(index) != currentItems.contains(index)) {
         // Rebuild the widget only in two cases:
         // 1- The item was in the old list and it is removed from the new list.
-        // 2- The item wasn't in the old list ant it is added to the new list.
+        // 2- The item wasn't in the old list and it is added to the new list.
         return true;
       }
     }
@@ -136,7 +137,7 @@ class _MyListItem extends ReactiveStatelessWidget {
   }
 }
 
-// For better optimization, this widget can be ReactiveStatelessWidget
+// For better optimization, this widget can be a ReactiveStatelessWidget
 //
 class _AddButton extends StatelessWidget {
   final Item item;