docs: 补充核心分层中文注释

components/platform/src/platform_stepper_driver.c

@@ -35,12 +35,22 @@
 #define PLATFORM_STEPPER_IN2_PIN         CONFIG_TQ_STEPPER_IN2_GPIO
 #define PLATFORM_STEPPER_IN3_PIN         CONFIG_TQ_STEPPER_IN3_GPIO
 #define PLATFORM_STEPPER_IN4_PIN         CONFIG_TQ_STEPPER_IN4_GPIO
+/*
+ * 2200us 是重新励磁和加速起点，较慢起步用于降低失步风险；加速/减速各48个半步，
+ * 短行程会按比例压缩。4128半步/圈包含电机步距、减速箱和八拍半步序列的综合标定，
+ * 修改电机或传动结构后必须重新实测标定。
+ */
 #define PLATFORM_STEPPER_START_DELAY_US  2200
 #define PLATFORM_STEPPER_ACCEL_STEPS     48
 #define PLATFORM_STEPPER_DECEL_STEPS     48
 #define PLATFORM_STEPPER_STEPS_PER_REV   4128.0f
+/*
+ * 释放保持电流最多等待1秒获取运动锁；单次旋转限制100度用于保护当前机械行程，
+ * 不是电机本体能力。扩大角度前必须确认实体限位和线缆余量。
+ */
 #define PLATFORM_STEPPER_POWER_OFF_WAIT_MS 1000
 #define PLATFORM_STEPPER_MAX_ROTATION_DEG 100.0f
+/* ESP32-S3 GPIO0-31 与 GPIO32以上使用不同输出寄存器组。 */
 #define PLATFORM_GPIO_LOW_BANK_MAX_PIN   31
 #define PLATFORM_GPIO_HIGH_BANK_OFFSET   32
 
@@ -53,6 +63,7 @@ static StaticSemaphore_t s_stepper_motion_mutex_buf;
 static int s_stepper_phase_index;
 static bool s_stepper_energized;
 
+/* 八拍半步序列兼顾转动平滑度和低速扭矩，反转时按相反方向遍历。 */
 static const int s_step_sequence[8][4] = {
     {1, 0, 0, 0},
     {1, 1, 0, 0},
@@ -91,6 +102,7 @@ static void add_gpio_level_mask(uint32_t *set0,
 
 static void set_motor_pins(int in1, int in2, int in3, int in4)
 {
+    /* 先计算寄存器掩码，再批量更新四相输出，缩短相位切换的时间偏差。 */
     uint32_t set0 = 0;
     uint32_t clr0 = 0;
     uint32_t set1 = 0;
@@ -219,6 +231,7 @@ static void calculate_motion_segments(int steps,
                                       int *out_constant_steps,
                                       int *out_decel_steps)
 {
+    /* 短行程按比例缩短加减速段，确保三段步数之和不超过总步数。 */
     int accel_steps = PLATFORM_STEPPER_ACCEL_STEPS;
     int decel_steps = PLATFORM_STEPPER_DECEL_STEPS;
 
@@ -278,6 +291,7 @@ static esp_err_t rotate_with_accel(int steps,
                                    int timeout_ms,
                                    int64_t start_ms)
 {
+    /* 每步动态计算延时形成加速、匀速、减速曲线，并在步间检查总超时。 */
     int accel_steps = 0;
     int constant_steps = 0;
     int decel_steps = 0;
@@ -340,6 +354,7 @@ esp_err_t platform_stepper_driver_rotate_angle_with_accel(float angle,
                                                           int target_delay_us,
                                                           int timeout_ms)
 {
+    /* 角度先换算为整数半步；方向只决定相位遍历方向，不改变加速曲线。 */
     if (!ensure_stepper_motion_mutex()) {
         return ESP_ERR_INVALID_STATE;
     }
@@ -406,6 +421,7 @@ esp_err_t platform_stepper_driver_rotate_angle_with_accel(float angle,
 
 esp_err_t platform_stepper_driver_release_hold(int timeout_ms)
 {
+    /* 与运动使用同一互斥锁，保证释放线圈不会发生在相位更新中间。 */
     if (timeout_ms < 0) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -431,5 +447,6 @@ esp_err_t platform_stepper_driver_release_hold(int timeout_ms)
 
 void platform_stepper_driver_power_off(void)
 {
+    /* 紧急断电直接清零相线；常规并发路径应优先使用 release_hold。 */
     (void)platform_stepper_driver_release_hold(PLATFORM_STEPPER_POWER_OFF_WAIT_MS);
 }