docs: document trajectory execution contracts

ClumsyPilot/ParkrobTrajplanner/TrajectoryExecution/GearSwitchStateMachine.cs

@@ -3,13 +3,16 @@ using MultiWheelC.TrajectoryPlanning.CoarsePath;
 
 namespace MultiWheelC.TrajectoryPlanning.EMPlanner;
 
-/// <summary>Pure caller-clocked state machine for a zero-speed direction change.</summary>
+/// <summary>纯 caller-clocked 的零速换向状态机；只依据调用方时间、测量速度和方向确认推进状态。</summary>
 public sealed class GearSwitchStateMachine
 {
     private readonly double stopSpeedToleranceMetersPerSecond;
     private readonly TimeSpan zeroSpeedHoldDuration;
     private DateTimeOffset? zeroSpeedSince;
 
+    /// <summary>创建换向状态机。</summary>
+    /// <param name="stopSpeedToleranceMetersPerSecond">判定已停稳的绝对带符号速度上限，单位 m/s。</param>
+    /// <param name="zeroSpeedHoldSeconds">发送方向请求前必须连续保持停稳的时长，单位 s。</param>
     public GearSwitchStateMachine(double stopSpeedToleranceMetersPerSecond, double zeroSpeedHoldSeconds)
     {
         if (!IsNonNegativeFinite(stopSpeedToleranceMetersPerSecond))
@@ -21,8 +24,18 @@ public sealed class GearSwitchStateMachine
         zeroSpeedHoldDuration = TimeSpan.FromSeconds(zeroSpeedHoldSeconds);
     }
 
+    /// <summary>当前不可回退的换向状态；初始为 <see cref="GearSwitchState.Following"/>。</summary>
     public GearSwitchState State { get; private set; } = GearSwitchState.Following;
 
+    /// <summary>基于调用方时刻、测量速度和边界语义推进一次换向状态。</summary>
+    /// <param name="now">调用方当前时刻，用于计算零速 dwell，不读取系统时钟。</param>
+    /// <param name="measuredSignedSpeed">测量带符号纵向速度，单位 m/s。</param>
+    /// <param name="desiredDirection">轨迹要求的实际行驶方向。</param>
+    /// <param name="currentDirection">调用方确认的当前实际方向。</param>
+    /// <param name="directionConfirmed">调用方是否已确认硬件方向切换完成。</param>
+    /// <param name="atGearSwitchBoundary">选中点是否为精确换向接近边界。</param>
+    /// <param name="atTerminal">选中点是否为 Goal 或 RollingSafetyStop 终端。</param>
+    /// <returns>包含停零、一次换向请求、是否允许轨迹运动和完成语义的不可变状态更新。</returns>
     public GearSwitchStateUpdate Update(DateTimeOffset now, double measuredSignedSpeed, TravelDirection desiredDirection,
         TravelDirection currentDirection, bool directionConfirmed, bool atGearSwitchBoundary, bool atTerminal)
     {
@@ -117,6 +130,7 @@ public sealed class GearSwitchStateMachine
     }
 }
 
+/// <summary>一次换向状态机更新的不可变安全决策，供执行器映射为零速度/制动或轨迹跟随命令。</summary>
 public sealed class GearSwitchStateUpdate
 {
     internal GearSwitchStateUpdate(GearSwitchState state, bool holdZero, bool requestDirectionChange,
@@ -130,14 +144,17 @@ public sealed class GearSwitchStateUpdate
         Reason = reason ?? string.Empty;
     }
 
+    /// <summary>更新后的换向状态。</summary>
     public GearSwitchState State { get; }
 
     public bool HoldZero { get; }
 
+    /// <summary>是否仅在本次更新请求一次方向变更。</summary>
     public bool RequestDirectionChange { get; }
 
     public bool AllowsTrajectoryMotion { get; }
 
+    /// <summary>是否因 Goal 或 RollingSafetyStop 完成轨迹并需要持续制动。</summary>
     public bool IsTrajectoryComplete { get; }
 
     public string Reason { get; }