Add comments

statig/src/awaitable/inner.rs

@@ -1,6 +1,4 @@
-use crate::awaitable::IntoStateMachine;
-#[cfg(feature = "async")]
-use crate::awaitable::{State, StateExt as _, Superstate};
+use crate::awaitable::{IntoStateMachine, State, StateExt, Superstate};
 use crate::Response;
 
 /// Private internal representation of a state machine that is used for the public types.
@@ -18,14 +16,14 @@ where
     M::State: State<M> + 'static,
     for<'sub> M::Superstate<'sub>: Superstate<M>,
 {
-    pub async fn init_with_context(&mut self, context: &mut M::Context<'_>) {
+    pub(crate) async fn init_with_context(&mut self, context: &mut M::Context<'_>) {
         let enter_levels = self.state.depth();
         self.state
             .enter(&mut self.shared_storage, context, enter_levels)
             .await;
     }
 
-    pub async fn handle_with_context(
+    pub(crate) async fn handle_with_context(
         &mut self,
         event: &M::Event<'_>,
         context: &mut M::Context<'_>,
@@ -42,7 +40,7 @@ where
     }
 
     /// Transition from the current state to the given target state.
-    pub async fn transition(&mut self, mut target: M::State, context: &mut M::Context<'_>) {
+    pub(crate) async fn transition(&mut self, mut target: M::State, context: &mut M::Context<'_>) {
         M::before_transition(&mut self.shared_storage, &self.state, &target).await;
 
         // Get the transition path we need to perform from one state to the next.

statig/src/awaitable/into_state_machine.rs

@@ -21,7 +21,7 @@ where
     where
         Self::State: 'sub;
 
-    /// Initial state of the state machine.
+    /// Constructor for the initial state of the state machine.
     fn initial() -> Self::State;
 
     /// Method that is called *before* an event is dispatched to a state or

statig/src/awaitable/state.rs

@@ -138,7 +138,9 @@ where
                         match response {
                             Response::Handled => break Response::Handled,
                             Response::Super => match superstate.superstate() {
-                                Some(s) => superstate = s,
+                                Some(superstate_of_superstate) => {
+                                    superstate = superstate_of_superstate
+                                }
                                 None => break Response::Handled,
                             },
                             Response::Transition(state) => break Response::Transition(state),
@@ -160,6 +162,11 @@ where
         mut levels: usize,
     ) -> impl Future<Output = ()> {
         async move {
+            // For each level we need to enter, climb that number of levels and excecute
+            // the superstate's entry action. We then decrement `levels` and again climb
+            // up the tree and execute the next entry action. We keep doing this until
+            // `levels` is equal to 1, which means the only entry action left to excecute
+            // is the state's own.
             while levels > 1 {
                 if let Some(mut superstate) = self.superstate() {
                     for _ in 2..levels {
@@ -188,10 +195,15 @@ where
         mut levels: usize,
     ) -> impl Future<Output = ()> {
         async move {
+            // First we need to excucute that state's own exit action.
             if levels >= 1 {
                 self.call_exit_action(shared_storage, context).await;
             }
 
+            // For each level we need to exit, climb up one level in the tree and
+            // execute the superstate's exit action, then decrement `levels`. As long as
+            // `levels` is greater then 1, we keep climbing up the three and excecute
+            // that superstate exit action.
             if let Some(mut superstate) = self.superstate() {
                 while levels > 1 {
                     superstate.call_exit_action(shared_storage, context).await;

statig/src/blocking/inner.rs

@@ -1,4 +1,4 @@
-use crate::blocking::{self, IntoStateMachine, StateExt as _};
+use crate::blocking::{IntoStateMachine, State, StateExt, Superstate};
 use crate::Response;
 
 /// Private internal representation of a state machine that is used for the public types.
@@ -13,18 +13,22 @@ where
 impl<M> Inner<M>
 where
     M: IntoStateMachine,
-    M::State: blocking::State<M>,
-    for<'sub> M::Superstate<'sub>: blocking::Superstate<M>,
+    M::State: State<M>,
+    for<'sub> M::Superstate<'sub>: Superstate<M>,
 {
     /// Initialize the state machine by executing all entry actions towards the initial state.
-    pub fn init_with_context(&mut self, context: &mut M::Context<'_>) {
+    pub(crate) fn init_with_context(&mut self, context: &mut M::Context<'_>) {
         let enter_levels = self.state.depth();
         self.state
             .enter(&mut self.shared_storage, context, enter_levels);
     }
 
     /// Handle the given event.
-    pub fn handle_with_context(&mut self, event: &M::Event<'_>, context: &mut M::Context<'_>) {
+    pub(crate) fn handle_with_context(
+        &mut self,
+        event: &M::Event<'_>,
+        context: &mut M::Context<'_>,
+    ) {
         let response = self.state.handle(&mut self.shared_storage, event, context);
         match response {
             Response::Super => {}
@@ -34,7 +38,7 @@ where
     }
 
     /// Transition from the current state to the given target state.
-    pub fn transition(&mut self, mut target: M::State, context: &mut M::Context<'_>) {
+    pub(crate) fn transition(&mut self, mut target: M::State, context: &mut M::Context<'_>) {
         M::before_transition(&mut self.shared_storage, &target, &self.state);
 
         // Get the transition path we need to perform from one state to the next.

statig/src/blocking/into_state_machine.rs

@@ -19,7 +19,7 @@ where
     where
         Self::State: 'sub;
 
-    /// Initial state of the state machine.
+    /// Constructor for the initial state of the state machine.
     fn initial() -> Self::State;
 
     /// Method that is called *before* an event is dispatched to a state or