still working on documentation

docs/state-machine/expression-tree-transformation.md

@@ -10,23 +10,24 @@ State machine generation involves converting user expression trees into state ma
 This process involves several steps, including tree traversal, state creation, and managing state transitions. The transformation
 process is essential for handling complex branching scenarios like conditional expressions and asynchronous operations.
 
-**The first step** transforms flow control constructs (such as if, switch, loops, and awaits) in the expression tree into a 
-state tree that can be used to generate a flattened goto state machine. This step systematically traverses the expression tree
-and replaces branching constructs with state nodes that manage control flow using transitions and goto operations. This step also 
-identifies variables that persist across state transitions.
+**The first step** in this process transforms flow control constructs (such as if, switch, loops, and awaits) in the expression 
+tree into a state tree that can be used to generate a flattened goto state machine. This step systematically traverses the expression 
+tree and replaces branching constructs with state nodes that manage control flow using transitions and goto operations. This step 
+also identifies variables that persist across state transitions.
+
+## Implementation Overview
 
-## GotoTransformerVisitor
 The `GotoTransformerVisitor` is responsible for traversing the expression tree and transforming its flow control constructs into  
 state machine nodes that use goto operations. This is where flow control constructs like conditionals, switches, and loops are
 turned into labeled states. The conversion to a state node structure enables the state machine to correctly represent the original 
 control flow while allowing for asynchronous execution that must suspend and resume operations.
 
 ### Traversing the Expression Tree
-The visitor pattern is employed to traverse the expression tree and create the state node representation. Each expression in the 
-expression tree is visited and potentially transformed into one or more state nodes.
+The Expression visitor pattern is employed to traverse the expression tree and create the state node representation. Each expression
+in the expression tree is visited and potentially transformed into one or more state nodes.
 
-### Understanding the StateContext
-The `GotoTransformerVisitor` uses a `StateContext` to manage the collection of state nodes that are created durring the expression 
+### The StateContext
+`GotoTransformerVisitor` uses a `StateContext` to manage the collection of state nodes that are created durring the expression 
 visit, and to track the transitions between them. The context keeps track of branching nodes, await continuations, and variables, 
 and links states into a tree based goto flow that will be used to generate the final state machine.
 
@@ -36,9 +37,6 @@ may complete immediately, or complete eventually. Eventual completions require t
 has been completed. The transformation process must handle these paths correctly by generating state nodes that represent the 
 awaiting and resumption of execution.
 
-- **Understanding the AwaitExpression:** The AwaitExpression is an asynchronous construct that represents an await operation. 
-  It requires special handling to ensure the state machine properly pauses and resumes.
-
 ### Handling Branching
 Branching in the expression tree is one of the most important transformations. The state machine must correctly handle various types of
 branching, ensuring that all possible branches are visited and correctly mapped to states.
@@ -86,7 +84,7 @@ tree so we can correctly re-join branches to the main flow. This is crucial for
 
 #### Example: `VisitConditional` Method
 
-Let's rereview the `VisitConditional` method to see how the tail node is used:
+Let's rereview the `VisitConditional` method to see how branching is managed:
 
 ```csharp
 protected override Expression VisitConditional(ConditionalExpression node) 
@@ -141,4 +139,4 @@ protected override Expression VisitConditional(ConditionalExpression node)
 - It ensures that state transitions are correctly managed, in branching constructs.
 - It is updated when new branching states are added, and when entering or exiting branching constructs.
 - The `_tailIndex` tracks the current branch segment from the last branching state node, not from the root of the state tree,
-  ensuring correct state transitions within nested branches. 
+  ensuring correct state transitions within nested branches. 

docs/state-machine/state-machine-builder.md

@@ -21,8 +21,8 @@ and wiring the execution flow according to the control constructs defined during
 The `StateMachineBuilder` class creates and manages state machines. It constructs state machine types that manage control flow 
 across asynchronous calls by creating appropriate state transitions and handling task results or exceptions.
 
-## StateMachineBuilder
-The `StateMachineBuilder` creates a state machine by emitting Types, IL, and building expression trees that correspond to the transformed states. 
+## Implementation Overview
+`StateMachineBuilder` creates a state machine by emitting Types, IL, and building expression trees that correspond to the transformed states. 
 It ensures that the state machine can handle asynchronous tasks, manage state transitions, and resolve variables across different states. This 
 transformation allows for asynchronous tasks to be suspended and resumed without blocking the main execution thread.