docs: enhance StateMachine and SM classes with additional methods and documentation

Author: jasonyang-ee

Application/Inc/StateMachine.hpp

@@ -9,13 +9,23 @@
 #include <vector>
 #include <ranges>
 
+/// @brief Values injected into actions and guards.
 using Injection = std::vector<std::any>;
+
+/// @brief Optional transition action callback.
+/// @see std::function<void()>
 using Action    = std::optional<std::function<void()>>;
+
+/// @brief Optional guard predicate for transitions.
+/// @return true if transition is allowed.
 using Guard     = std::optional<std::function<bool()>>;
 
+/// @brief Forward declaration of the state machine engine.
 template <typename Parent>
 class SM;
 
+/// @brief Container for states, transitions, and injections of the state machine.
+/// @tparam Parent Type defining State and Event.
 template<typename Parent>
 struct StateMachineContainer {
     using State      = typename Parent::State;
@@ -24,21 +34,44 @@ struct StateMachineContainer {
     using Transition = std::tuple< State, Event, State, Guard, Action, Injection >;
     using Anonymous  = std::tuple< State, State, Guard, Action, Injection >;
 
+    /// @brief Current active state of the state machine.
     State                  currentState;
+
+    /// @brief Registered state entries with guards and entry actions.
     std::vector<Entry>      entries;
+
+    /// @brief Event-driven transitions.
     std::vector<Transition> transitions;
+
+    /// @brief Automatic transitions executed without an explicit event.
     std::vector<Anonymous>  anonymous;
+
+    /// @brief Values injected into callbacks during state changes.
     Injection               injections;
 
     // Member convenience methods
+    /// @brief Trigger a state machine event.
+    /// @tparam ExternalInjection Types of additional data to inject.
+    /// @param event Event to trigger.
+    /// @param args Optional injection values.
     template<typename... ExternalInjection>
     void triggerEvent(typename Parent::Event event, ExternalInjection&&... args) {
         SM<Parent>::triggerEvent(event, *this, std::forward<ExternalInjection>(args)...);
     }
+
+    /// @brief Set a new state directly, bypassing events.
+    /// @tparam ExternalInjection Types of additional data to inject.
+    /// @param state Target state to set.
+    /// @param args Optional injection values.
     template<typename... ExternalInjection>
     void setState(typename Parent::State state, ExternalInjection&&... args) {
         SM<Parent>::setState(state, *this, std::forward<ExternalInjection>(args)...);
     }
+
+    /// @brief Run anonymous transitions until none remain.
+    /// @tparam ExternalInjection Types of additional data to inject.
+    /// @param args Optional injection values.
+    /// @return true if any anonymous transition executed.
     template<typename... ExternalInjection>
     bool runAnonymous(ExternalInjection&&... args) {
         return SM<Parent>::runAnonymous(*this, std::forward<ExternalInjection>(args)...);
@@ -48,13 +81,20 @@ struct StateMachineContainer {
 template<typename Parent>
 using StateMachine = StateMachineContainer<Parent>;
 
+/// @brief State machine engine implementing transitions and state changes.
+/// @tparam Parent Type defining State and Event.
 template <typename Parent>
 class SM {
    public:
     using State = typename Parent::State;
     using Event = typename Parent::Event;
     using StateMachine = StateMachineContainer<Parent>;
 
+    /// @brief Process an event and transition state if matching.
+    /// @tparam ExternalInjection Types of optional injection values.
+    /// @param event Event to handle.
+    /// @param sm StateMachine instance to operate on.
+    /// @param args Additional values for injection.
     template <typename... ExternalInjection>
     static void triggerEvent(Parent::Event event, StateMachine &sm, ExternalInjection... args) {
         auto it = std::ranges::find_if(sm.transitions.begin(), sm.transitions.end(), [&](const auto &t) {
@@ -69,6 +109,11 @@ class SM {
         while(runAnonymous(sm, std::forward<ExternalInjection>(args)...)) {}
     }
 
+    /// @brief Force set the state with injection values.
+    /// @tparam ExternalInjection Types of optional injection values.
+    /// @param state New state to set.
+    /// @param sm StateMachine instance to operate on.
+    /// @param args Additional values for injection.
     template <typename... ExternalInjection>
     static void setState(Parent::State state, StateMachine &sm, ExternalInjection... args) {
         auto it = std::ranges::find_if(sm.entries.begin(), sm.entries.end(),
@@ -82,6 +127,11 @@ class SM {
         while(runAnonymous(sm, std::forward<ExternalInjection>(args)...)) {}
     }
 
+    /// @brief Execute an anonymous transition if the current state matches.
+    /// @tparam ExternalInjection Types of optional injection values.
+    /// @param sm StateMachine instance to operate on.
+    /// @param args Additional values for injection.
+    /// @return true if a transition occurred.
     template <typename... ExternalInjection>
     static bool runAnonymous(StateMachine &sm, ExternalInjection... args) {
         auto it = std::ranges::find_if(sm.anonymous.begin(), sm.anonymous.end(),
@@ -91,20 +141,32 @@ class SM {
             auto [fromState, nextState, guard, action, injection] = *it;
             updateInjection(sm, injection, std::forward<ExternalInjection>(args)...);
             handleStateChange(sm, nextState, guard, action);
-			return true;
+            return true;
         }
-		return false;
+        return false;
     }
 
+    /// @brief Retrieve the current state from the state machine.
+    /// @param sm StateMachine instance.
+    /// @return Current active state.
     static Parent::State getState(StateMachine &sm) { return sm.currentState; }
 
    private:
+    /// @brief Evaluate guard and perform state change and action.
+    /// @param sm Instance to update.
+    /// @param nextState State to transition to.
+    /// @param guard Optional guard predicate.
+    /// @param action Optional action to execute.
     static void handleStateChange(StateMachine &sm, Parent::State nextState, Guard guard, Action action) {
         if (guard && !(*guard)()) return;
         sm.currentState = nextState;
         if (action) (*action)();
     }
 
+    /// @brief Populate the injection vector for upcoming callbacks.
+    /// @param sm Instance whose injections will be updated.
+    /// @param injection Predefined injection values.
+    /// @param args Additional values to inject.
     template <typename... ExternalInjection>
     static void updateInjection(StateMachine &sm, Injection injection, ExternalInjection &&...args) {
         if (!injection.empty()) {