Add XML docs

StoneRed.LogicSimulator.Simulation/EventCircuitSimulator.cs

@@ -2,12 +2,25 @@ using System.Linq.Expressions;
 
 namespace StoneRed.LogicSimulator.Simulation;
 
+/// <summary>
+/// An event-driven circuit simulator that uses queue-based change propagation.
+/// Only gates with changed inputs are evaluated, making it efficient for circuits with localized activity.
+/// </summary>
+/// <remarks>
+/// This simulator uses a dirty-marking propagation queue. When a gate's output changes,
+/// only the gates connected to it are queued for re-evaluation. This is more efficient
+/// than <see cref="CycleCircuitSimulator"/> for sparse circuits where most gates remain stable.
+/// </remarks>
 public sealed class EventCircuitSimulator : SimulatorBase
 {
     private Action<int[], int[], int[], int>[] gateEvaluators = [];
     private readonly Queue<int> activeQueue = new();
     private bool[] inQueue = [];
 
+    /// <summary>
+    /// Called when a gate is added to ensure internal arrays are properly sized.
+    /// </summary>
+    /// <param name="gateId">The ID of the newly added gate.</param>
     protected override void OnGateAdded(int gateId)
     {
         if (inQueue.Length != gateKinds.Count)
@@ -16,6 +29,9 @@ public sealed class EventCircuitSimulator : SimulatorBase
         }
     }
 
+    /// <summary>
+    /// Resets the circuit to initial state and queues all gates for initial evaluation.
+    /// </summary>
     public override void Reset()
     {
         base.Reset();
@@ -27,6 +43,10 @@ public sealed class EventCircuitSimulator : SimulatorBase
         }
     }
 
+    /// <summary>
+    /// Called when a source gate's value changes. Queues the source for propagation.
+    /// </summary>
+    /// <param name="gateId">The ID of the source gate that changed.</param>
     protected override void OnSourceChanged(int gateId)
     {
         Enqueue(gateId);
@@ -41,6 +61,10 @@ public sealed class EventCircuitSimulator : SimulatorBase
         }
     }
 
+    /// <summary>
+    /// Executes one simulation step by processing all pending changes in the queue.
+    /// Continues until the queue is empty (all changes have propagated).
+    /// </summary>
     public override void Step()
     {
         EnsureCompiled();
@@ -84,6 +108,12 @@ public sealed class EventCircuitSimulator : SimulatorBase
         }
     }
 
+    /// <summary>
+    /// Runs the simulation until the queue is empty (circuit is stable) or maxSteps is reached.
+    /// </summary>
+    /// <param name="maxSteps">Maximum number of steps to execute.</param>
+    /// <param name="steps">Output parameter containing the number of steps executed.</param>
+    /// <returns>True if the circuit stabilized (queue is empty); false if maxSteps was exceeded.</returns>
     public override bool TryRunUntilStable(int maxSteps, out int steps)
     {
         steps = 0;
@@ -106,6 +136,10 @@ public sealed class EventCircuitSimulator : SimulatorBase
         return activeQueue.Count == 0;
     }
 
+    /// <summary>
+    /// Compiles per-gate evaluators as separate compiled lambda expressions.
+    /// Each gate has its own evaluator function for efficient event-driven execution.
+    /// </summary>
     protected override void CompileEngine()
     {
         gateEvaluators = new Action<int[], int[], int[], int>[gateKinds.Count];
@@ -126,11 +160,18 @@ public sealed class EventCircuitSimulator : SimulatorBase
         }
     }
 
+    /// <summary>
+    /// Creates a new instance of EventCircuitSimulator for internal use (e.g., LUT computation).
+    /// </summary>
+    /// <returns>A new EventCircuitSimulator instance.</returns>
     protected override SimulatorBase CreateInternalSimulator()
     {
         return new EventCircuitSimulator();
     }
 
+    /// <summary>
+    /// Ensures internal storage arrays are properly sized for the current gate count.
+    /// </summary>
     protected override void EnsureStorage()
     {
         base.EnsureStorage();