FSM Documentation

Moose Development/Moose/Core/Fsm.lua

@@ -67,9 +67,16 @@
 -- The **Event Triggers** are methods that are defined by the FSM, which the mission designer can use to implement the workflow.
 -- Most of the time, these Event Triggers are used within the Transition Handler methods, so that a workflow is created running through the state machine.
 -- 
--- The underlying chapters provide more details on each of these topics. 
+-- As explained above, a FSM supports **Linear State Transitions** and **Hierarchical State Transitions**, and both can be mixed to make a comprehensive FSM implementation.
+-- The below documentation has a seperate chapter explaining both transition modes, taking into account the **Transition Rules**, **Transition Handlers** and **Event Triggers**.
 -- 
--- ## 1.1) FSM Transition Rules
+-- ## 1.1) FSM Linear Transitions
+-- 
+-- Linear Transitions are Transition Rules allowing an FSM to transition from one or multiple possible **From** state(s) towards a **To** state upon a Triggered **Event**.
+-- The Lineair transition rule evaluation will always be done from the **current state* of the FSM.
+-- If no valid Transition Rule can be found in the FSM, the FSM will log an error and stop.
+-- 
+-- ### 1.1.1) FSM Transition Rules
 -- 
 -- The FSM has transition rules that it follows and validates, as it walks the process. 
 -- These rules define when an FSM can transition from a specific state towards an other specific state upon a triggered event.
@@ -78,7 +85,7 @@
 -- 
 -- The initial state can be defined using the method @{#FSM.SetStartState}(). The default start state of an FSM is "None".
 -- 
--- ## 1.2) Transition Handling
+-- ### 1.1.2) Transition Handling
 -- 
 -- ![Transition Handlers](..\Presentations\FSM\Dia4.jpg)
 -- 
@@ -100,7 +107,7 @@
 -- 
 -- On top, each of these methods can have a variable amount of parameters passed. See the example in section 1.3.
 -- 
--- ## 1.3) Event Triggers
+-- ### 1.1.3) Event Triggers
 -- 
 -- ![Event Triggers](..\Presentations\FSM\Dia5.jpg)
 -- 
@@ -138,7 +145,7 @@
 -- 
 -- Because ... When Event was asynchronously processed after 5 seconds, Amount was set to 2. So be careful when processing and passing values and objects in asynchronous processing!
 -- 
--- ## 1.4) Transitioning Example
+-- ### 1.1.4) Linear Transitioning Example
 -- 
 -- This example creates a new FsmDemo object from class FSM.
 -- It will set the start state of FsmDemo to Green.
@@ -201,14 +208,14 @@
 -- 
 -- ### Some additional comments:
 -- 
--- Note that transition rules can be declared with a few variations:
+-- Note that transition rules **can be declared with a few variations**:
 -- 
---   * The From states can be a table of strings, indicating that the transition rule will be valid if the current state of the FSM will be one of the given From states.
---   * The From state can be a "*", indicating that the transition rule will always be valid, regardless of the current state of the FSM.
+--   * The From states can be **a table of strings**, indicating that the transition rule will be valid **if the current state** of the FSM will be **one of the given From states**.
+--   * The From state can be a **"*"**, indicating that **the transition rule will always be valid**, regardless of the current state of the FSM.
 -- 
--- The below code fragment extends the FsmDemo, emonstrating multiple From states declared as a table, in an additional transition rule.
--- The new event Stop will cancel the Switching process.
--- The transtion for event Stop can be executed if the current state of the FSM is either "Red" or "Green".
+-- The below code fragment extends the FsmDemo, demonstrating multiple **From states declared as a table**, in an additional transition rule.
+-- The new event **Stop** will cancel the Switching process.
+-- The transition for event Stop can be executed if the current state of the FSM is either "Red" or "Green".
 -- 
 --      local FsmDemo = FSM:New() -- #FsmDemo
 --      FsmDemo:SetStartState( "Green" )
@@ -223,10 +230,14 @@
 -- So... When FsmDemo:Stop() is being triggered, the state of FsmDemo will transition from Red or Green to Stopped.
 -- And there is no transition handling method defined for that transition, thus, no new event is being triggered causing the FsmDemo process flow to halt.
 -- 
--- ## 1.5) Sub-FSM Embedding
+-- ## 1.5) FSM Hierarchical Transitions
 -- 
--- The FSM can embed Sub-FSMs that will execute and return multiple possible **Return (End) States**.  
--- Depending upon which state is returned, the main FSM can continue the flow triggering different events.
+-- Hierarchical Transitions allow to re-use readily available and implemented FSMs.
+-- This becomes in very useful for mission building, where mission designers build complex processes and workflows, 
+-- combining smaller FSMs to one single FSM.
+-- 
+-- The FSM can embed **Sub-FSMs** that will execute and return **multiple possible Return (End) States**.  
+-- Depending upon **which state is returned**, the main FSM can continue the flow **triggering specific events**.
 -- 
 -- The method @{#FSM.AddProcess}() adds a new Sub-FSM to the FSM.  
 --
@@ -252,11 +263,11 @@
 -- 
 -- ### Contributions: 
 -- 
---   * **Pikey**: Review of documentation.
+--   * [**Pikey**](https://forums.eagle.ru/member.php?u=62835): Review of documentation & advice for improvements.
 -- 
 -- ### Authors: 
 -- 
---   * **FlightControl**: Design & Programming & documenting.
+--   * [**FlightControl**](https://forums.eagle.ru/member.php?u=89536): Design & Programming & documentation.
 --
 -- @module Fsm
 

docs/Documentation/Cargo.html

@@ -2411,7 +2411,6 @@ The UNIT carrying the package.</p>
 		<dl class="function">
 <dt>
 
-		<em></em>
 <a id="#(AI_CARGO_UNIT).CargoCarrier" >
 <strong>AI_CARGO_UNIT.CargoCarrier</strong>
 </a>

docs/Documentation/Fsm.html

@@ -143,9 +143,16 @@ The method can then define its own custom logic to implement the FSM workflow, a
 <p>The <strong>Event Triggers</strong> are methods that are defined by the FSM, which the mission designer can use to implement the workflow.
 Most of the time, these Event Triggers are used within the Transition Handler methods, so that a workflow is created running through the state machine.</p>
 
-<p>The underlying chapters provide more details on each of these topics. </p>
+<p>As explained above, a FSM supports <strong>Linear State Transitions</strong> and <strong>Hierarchical State Transitions</strong>, and both can be mixed to make a comprehensive FSM implementation.
+The below documentation has a seperate chapter explaining both transition modes, taking into account the <strong>Transition Rules</strong>, <strong>Transition Handlers</strong> and <strong>Event Triggers</strong>.</p>
 
-<h2>1.1) FSM Transition Rules</h2>
+<h2>1.1) FSM Linear Transitions</h2>
+
+<p>Linear Transitions are Transition Rules allowing an FSM to transition from one or multiple possible <strong>From</strong> state(s) towards a <strong>To</strong> state upon a Triggered <strong>Event</strong>.
+The Lineair transition rule evaluation will always be done from the <em>*current state</em> of the FSM.
+If no valid Transition Rule can be found in the FSM, the FSM will log an error and stop.</p>
+
+<h3>1.1.1) FSM Transition Rules</h3>
 
 <p>The FSM has transition rules that it follows and validates, as it walks the process. 
 These rules define when an FSM can transition from a specific state towards an other specific state upon a triggered event.</p>
@@ -154,7 +161,7 @@ These rules define when an FSM can transition from a specific state towards an o
 
 <p>The initial state can be defined using the method <a href="##(FSM).SetStartState">FSM.SetStartState</a>(). The default start state of an FSM is "None".</p>
 
-<h2>1.2) Transition Handling</h2>
+<h3>1.1.2) Transition Handling</h3>
 
 <p><img src="..\Presentations\FSM\Dia4.jpg" alt="Transition Handlers"/></p>
 
@@ -180,7 +187,7 @@ These parameters are on the correct order: From, Event, To:</p>
 
 <p>On top, each of these methods can have a variable amount of parameters passed. See the example in section 1.3.</p>
 
-<h2>1.3) Event Triggers</h2>
+<h3>1.1.3) Event Triggers</h3>
 
 <p><img src="..\Presentations\FSM\Dia5.jpg" alt="Event Triggers"/></p>
 
@@ -223,7 +230,7 @@ Event will be processed after 5 seconds, and Amount is given as a parameter.</p>
 
 <p>Because ... When Event was asynchronously processed after 5 seconds, Amount was set to 2. So be careful when processing and passing values and objects in asynchronous processing!</p>
 
-<h2>1.4) Transitioning Example</h2>
+<h3>1.1.4) Linear Transitioning Example</h3>
 
 <p>This example creates a new FsmDemo object from class FSM.
 It will set the start state of FsmDemo to Green.
@@ -292,16 +299,16 @@ and one additional parameter that was given when the event was triggered, which
 
 <h3>Some additional comments:</h3>
 
-<p>Note that transition rules can be declared with a few variations:</p>
+<p>Note that transition rules <strong>can be declared with a few variations</strong>:</p>
 
 <ul>
-    <li>The From states can be a table of strings, indicating that the transition rule will be valid if the current state of the FSM will be one of the given From states.</li>
-    <li>The From state can be a "*", indicating that the transition rule will always be valid, regardless of the current state of the FSM.</li>
+    <li>The From states can be <strong>a table of strings</strong>, indicating that the transition rule will be valid <strong>if the current state</strong> of the FSM will be <strong>one of the given From states</strong>.</li>
+    <li>The From state can be a <strong>"*"</strong>, indicating that <strong>the transition rule will always be valid</strong>, regardless of the current state of the FSM.</li>
 </ul>
 
-<p>The below code fragment extends the FsmDemo, emonstrating multiple From states declared as a table, in an additional transition rule.
-The new event Stop will cancel the Switching process.
-The transtion for event Stop can be executed if the current state of the FSM is either "Red" or "Green".</p>
+<p>The below code fragment extends the FsmDemo, demonstrating multiple <strong>From states declared as a table</strong>, in an additional transition rule.
+The new event <strong>Stop</strong> will cancel the Switching process.
+The transition for event Stop can be executed if the current state of the FSM is either "Red" or "Green".</p>
 
 <pre><code> local FsmDemo = FSM:New() -- #FsmDemo
  FsmDemo:SetStartState( "Green" )
@@ -318,10 +325,14 @@ The transtion for event Stop can be executed if the current state of the FSM is
 <p>So... When FsmDemo:Stop() is being triggered, the state of FsmDemo will transition from Red or Green to Stopped.
 And there is no transition handling method defined for that transition, thus, no new event is being triggered causing the FsmDemo process flow to halt.</p>
 
-<h2>1.5) Sub-FSM Embedding</h2>
+<h2>1.5) FSM Hierarchical Transitions</h2>
 
-<p>The FSM can embed Sub-FSMs that will execute and return multiple possible <strong>Return (End) States</strong>. <br/>
-Depending upon which state is returned, the main FSM can continue the flow triggering different events.</p>
+<p>Hierarchical Transitions allow to re-use readily available and implemented FSMs.
+This becomes in very useful for mission building, where mission designers build complex processes and workflows, 
+combining smaller FSMs to one single FSM.</p>
+
+<p>The FSM can embed <strong>Sub-FSMs</strong> that will execute and return <strong>multiple possible Return (End) States</strong>. <br/>
+Depending upon <strong>which state is returned</strong>, the main FSM can continue the flow <strong>triggering specific events</strong>.</p>
 
 <p>The method <a href="##(FSM).AddProcess">FSM.AddProcess</a>() adds a new Sub-FSM to the FSM.  </p>
 
@@ -352,13 +363,13 @@ YYYY-MM-DD: CLASS:<strong>NewFunction( Params )</strong> added</p>
 <h3>Contributions:</h3>
 
 <ul>
-    <li><strong>Pikey</strong>: Review of documentation.</li>
+    <li><a href="https://forums.eagle.ru/member.php?u=62835"><strong>Pikey</strong></a>: Review of documentation &amp; advice for improvements.</li>
 </ul>
 
 <h3>Authors:</h3>
 
 <ul>
-    <li><strong>FlightControl</strong>: Design &amp; Programming &amp; documenting.</li>
+    <li><a href="https://forums.eagle.ru/member.php?u=89536"><strong>FlightControl</strong></a>: Design &amp; Programming &amp; documentation.</li>
 </ul>
 
 

docs/Documentation/Spawn.html

@@ -2166,7 +2166,7 @@ when nothing was spawned.</p>
 		<dl class="function">
 <dt>
 
-		<em></em>
+		<em>#number</em>
 <a id="#(SPAWN).SpawnMaxGroups" >
 <strong>SPAWN.SpawnMaxGroups</strong>
 </a>
@@ -2183,7 +2183,7 @@ when nothing was spawned.</p>
 		<dl class="function">
 <dt>
 
-		<em></em>
+		<em>#number</em>
 <a id="#(SPAWN).SpawnMaxUnitsAlive" >
 <strong>SPAWN.SpawnMaxUnitsAlive</strong>
 </a>