docs: 统一表达式读点注释并修正数组乱码

crates/oxide_emit/src/expr/assignment.rs

@@ -25,8 +25,9 @@ impl Emitter {
         if !ctx.register_update_names.iter().any(|n| n == name) {
             self.emit_const_write_guard(name, ctx)?;
         }
-        // 循环 update 段：被捕获绑定走寄存器 RMW（C 风格 for 每迭代 fresh，
+        // 循环 update 段：被捕获绑定走寄存器 RMW——C 风格 for 的 let/const
-        // update 写寄存器供下一迭代 fresh 拷贝，不污染本迭代闭包捕获的 cell）。
+        // 循环变量每迭代新分配一个 cell，update 写寄存器供其拷入，不污染本迭代
+        // 闭包捕获的 cell（机制见 `compile_ctx.rs` 的 `register_update_names` 字段文档）。
         if ctx.register_update_names.iter().any(|n| n == name) {
             if let Some(reg) = ctx.scopes.symbols.lookup_any(name) {
                 if ctx.targets_readonly_builtin(name, reg) {
@@ -118,7 +119,8 @@ impl Emitter {
             }
             ctx.inst(Inst::new(op, Operand::Reg(var_reg), Operand::Reg(rhs), Operand::None));
             if is_tier {
-                // 顶层已声明 var 复合赋值：新值落全局对象属性（A 侧单一真值）。
+                // 顶层已声明 var 复合赋值：新值写入全局对象属性（顶层 var 的唯一存储，
+                // 引擎侧不保留镜像副本）。
                 self.emit_tier_global_write(name, var_reg, ctx);
             } else if is_implicit {
                 self.emit_implicit_global_write(name, var_reg, ctx);
@@ -251,7 +253,8 @@ impl Emitter {
                         _ => return Err(format!("compound assignment operator {:?} not supported", assign.operator)),
                     };
                     if assign.operator == AssignmentOperator::Exponential {
-                        // 指数无独立二元指令，COMPOUND_EXP 语义 rd=rd^a：rhs 放 a 槽。
+                        // 指数无独立二元指令，COMPOUND_EXP 语义 rd=rd^a：rhs 放 a 操作数槽
+                        // （指令的三个操作数槽依次为 rd、a、b，a 槽紧随 rd）。
                         ctx.inst(Inst::new(op, Operand::Reg(val_reg), Operand::Reg(rhs), Operand::None));
                     } else {
                         ctx.inst(Inst::new(op, Operand::Reg(val_reg), Operand::Reg(val_reg), Operand::Reg(rhs)));
@@ -334,7 +337,8 @@ impl Emitter {
                     _ => return Err(format!("compound assignment operator {:?} not supported", assign.operator)),
                 };
                 if assign.operator == AssignmentOperator::Exponential {
-                    // 指数无独立二元指令，COMPOUND_EXP 语义 rd=rd^a：rhs 放 a 槽。
+                    // 指数无独立二元指令，COMPOUND_EXP 语义 rd=rd^a：rhs 放 a 操作数槽
+                    // （指令的三个操作数槽依次为 rd、a、b，a 槽紧随 rd）。
                     ctx.inst(Inst::new(op, Operand::Reg(val_reg), Operand::Reg(rhs), Operand::None));
                 } else {
                     ctx.inst(Inst::new(op, Operand::Reg(val_reg), Operand::Reg(val_reg), Operand::Reg(rhs)));
@@ -447,7 +451,8 @@ impl Emitter {
                                 // 严格模式未声明写：抛 ReferenceError，后续 LOAD_VAR 不可达。
                                 let _ = self.emit_strict_undeclared_write(name, ctx)?;
                             } else if is_tier {
-                                // 顶层已声明 var 逻辑赋值：新值落全局对象属性（A 侧单一真值）。
+                                // 顶层已声明 var 逻辑赋值：新值写入全局对象属性（顶层 var 的唯一存储，
+                                // 引擎侧不保留镜像副本）。
                                 self.emit_tier_global_write(name, val_reg, ctx);
                             } else {
                                 ctx.inst(Inst::new(
@@ -667,7 +672,8 @@ impl Emitter {
                 AssignmentOperator::Division => OpCode::DIV,
                 AssignmentOperator::Remainder => OpCode::MOD,
                 // 指数无 COMPOUND_* 对应（COMPOUND_EXP 只读 [Rd,A] 会忽略 rhs）：
-                // 走三寄存器 EXP，旧值在 a 槽（val_reg 兼 rd/a）、rhs 在 b 槽。
+                // 走三寄存器 EXP，旧值放 a 操作数槽（结果槽与 a 槽同寄存器）、
+                // rhs 放 b 操作数槽。
                 AssignmentOperator::Exponential => OpCode::EXP,
                 AssignmentOperator::BitwiseAnd => OpCode::BIT_AND,
                 AssignmentOperator::BitwiseOR => OpCode::BIT_OR,

crates/oxide_emit/src/expr/identifier.rs

@@ -45,9 +45,11 @@ impl Emitter {
             Err(err) => return Err(err),
         };
         let r = ctx.alloc_reg();
-        // 顶层已声明 var 裸读与未声明标识符读同形：读全局对象属性（A 侧单一真值），
+        // 顶层已声明 var 裸读与未声明标识符读同形：读全局对象属性（顶层 var 的唯一
-        // 缺失抛 ReferenceError（unresolvable）。tier 名属性由 GDI 序言创建（仅删除后
+        // 存储，引擎侧不保留镜像副本，见 `compile_ctx.rs` 的 `global_tier_names` 字段
-        // 缺失）；未声明名属性缺失即 unresolvable。已声明 var 不再落镜像 cell/槽。
+        // 文档），缺失抛 ReferenceError（unresolvable）。tier 名属性由
+        // GlobalDeclarationInstantiation（脚本顶层声明实例化）序言创建（仅删除后缺失）；
+        // 未声明名属性缺失即 unresolvable。已声明 var 不再落引擎侧镜像副本。
         if self.is_global_tier_name(ctx, name) || ctx.implicit_global_reads.contains(&var_reg) {
             let key_idx = ctx.add_constant(Constant::String(name.to_string()));
             ctx.inst(Inst::new(OpCode::LOAD_GLOBAL, Operand::Reg(r), Operand::Const(key_idx), Operand::None));
@@ -111,7 +113,8 @@ impl Emitter {
                 ));
             }
         } else if self.is_global_tier_name(ctx, name) {
-            // 顶层已声明 var：with 对象无该属性时回退读全局对象属性（A 侧单一真值）。
+            // 顶层已声明 var：with 对象无该属性时回退读全局对象属性（顶层 var 的唯一
+            // 存储，引擎侧不保留镜像副本）。
             let key_idx = ctx.add_constant(Constant::String(name.to_string()));
             ctx.inst(Inst::new(
                 OpCode::LOAD_GLOBAL,
@@ -147,8 +150,9 @@ impl Emitter {
             let _ = self.emit_throw_error("TypeError", "Assignment to constant variable", ctx);
             return;
         }
-        // 循环 update 段：被捕获绑定走寄存器而非 cell（C 风格 for 每迭代 fresh，
+        // 循环 update 段：被捕获绑定走寄存器而非 cell——C 风格 for 的 let/const
-        // update 写寄存器供下一迭代 fresh 拷贝，不污染本迭代闭包捕获的 cell）。
+        // 循环变量每迭代新分配一个 cell，update 写寄存器供其拷入，不污染本迭代
+        // 闭包捕获的 cell（机制见 `compile_ctx.rs` 的 `register_update_names` 字段文档）。
         if in_loop_update {
             if let Some(reg) = ctx.scopes.symbols.lookup_any(name) {
                 if ctx.targets_readonly_builtin(name, reg) {
@@ -203,7 +207,8 @@ impl Emitter {
             return;
         }
         if is_tier {
-            // 顶层已声明 var 裸写：落全局对象属性（A 侧单一真值），不写镜像槽。
+            // 顶层已声明 var 裸写：写入全局对象属性（顶层 var 的唯一存储，引擎侧不保留
+            // 镜像副本）。
             self.emit_tier_global_write(name, val_reg, ctx);
             return;
         }
@@ -216,8 +221,9 @@ impl Emitter {
         if is_implicit {
             self.emit_implicit_global_write(name, var_reg, ctx);
         } else if ctx.targets_writable_builtin(name, var_reg) {
-            // 可写内置名：值同步落全局对象属性（0x98 对既有可写属性仅更值、
+            // 可写内置名：值同步写入全局对象属性——`DEFINE_GLOBAL_PROP_C`（`0x98`，
-            // 保 e/c 位），否则镜像槽与 globalThis 反射失步。
+            // 见 `crates/oxide_bytecode/src/opcode.rs`）对既有可写属性仅更新值、不改变
+            // enumerable/configurable 位；否则内置名镜像槽与 globalThis 反射读到不同值。
             self.emit_global_put_write(name, var_reg, ctx);
         }
     }

crates/oxide_emit/src/expr/object/array.rs

@@ -22,8 +22,8 @@ impl Emitter {
             ctx.inst(Inst::new(OpCode::NEW_ARRAY, Operand::Reg(arr_reg), Operand::Imm(n), Operand::None));
             for (i, elem) in arr.elements.iter().enumerate() {
                 let Some(e) = elem.as_expression() else {
-                    // hole?????????????????????????
+                    // hole 元素：NEW_ARRAY 已按 n 预填本下标的自有属性（初值 undefined），
-                    // ??? delete ?????? hole meta?length ????
+                    // 显式删除使 hole 不是自有属性；length 不受 delete 影响，仍为 n。
                     let scratch = ctx.alloc_reg();
                     ctx.inst(Inst::inst_mov(Operand::Reg(scratch), Operand::Reg(arr_reg)));
                     let idx = ctx.add_constant(Constant::Int(i as i32));

crates/oxide_emit/src/expr/operator/mod.rs

@@ -229,9 +229,9 @@ impl Emitter {
                     let key_idx = ctx.add_constant(Constant::String(name.to_string()));
                     let reg = ctx.alloc_reg();
                     ctx.inst(Inst::delete_global_prop_c(Operand::Reg(reg), Operand::None, key_idx));
-                    // 隐式全局槽被真删后，同程序后续裸读该名须走全局对象属性
+                    // 隐式全局槽被真删后，同程序后续裸读该名须走全局对象属性（顶层 var
-                    // （A 侧单一真值）：缺失属性读抛 ReferenceError，delete 的
+                    // 的唯一存储，引擎侧不保留镜像副本）：缺失属性读抛 ReferenceError，
-                    // 真删效应在读侧可见。
+                    // delete 的真删效应在读侧可见。
                     if let Some((binding, _)) = ctx.scopes.symbols.lookup_any_binding(name) {
                         if ctx.is_implicit_global_reg(binding.reg) {
                             ctx.implicit_global_reads.insert(binding.reg);
@@ -349,10 +349,11 @@ impl Emitter {
             let in_with_dynamic = !ctx.with_stack.is_empty() && !ctx.is_with_internal_binding(name);
             let captured =
                 ctx.current_upvalue_captures.iter().any(|u| u.name == name) || ctx.captured_bindings.contains_key(name);
-            // 顶层已声明 var：typeof 读全局对象属性（A 侧单一真值），缺失 → "undefined"
+            // 顶层已声明 var：typeof 读全局对象属性（顶层 var 的唯一存储，引擎侧不保留
-            // （非抛，IsUnresolvableReference 语义）。未声明名同走此路（lookup 未命中）。
+            // 镜像副本），缺失 → "undefined"（非抛，IsUnresolvableReference 语义）。未声明名
-            // 隐式全局槽（未声明名读写登记）同走属性路：delete 真删后缺失 → "undefined"
+            // 同走此路（lookup 未命中）。隐式全局槽（未声明名读写登记）同走属性路：
-            // 而非经镜像槽读旧值或抛 ReferenceError（typeof 对 unresolvable 引用不抛）。
+            // delete 真删后缺失 → "undefined" 而非经引擎侧镜像副本读旧值或抛
+            // ReferenceError（typeof 对 unresolvable 引用不抛）。
             let binding = ctx.scopes.symbols.lookup_any_binding(name);
             let implicit_global = binding.is_some_and(|(b, _)| ctx.is_implicit_global_reg(b.reg));
             let is_tier = self.is_global_tier_name(ctx, name);
@@ -611,8 +612,9 @@ impl Emitter {
         }
         let uv_idx = ctx.current_upvalue_captures.iter().position(|u| u.name == name);
         let captured_cell = ctx.captured_bindings.get(name).copied();
-        // 循环 update 段：被捕获绑定走寄存器 INC/DEC（C 风格 for 每迭代 fresh，
+        // 循环 update 段：被捕获绑定走寄存器 INC/DEC——C 风格 for 的 let/const
-        // update 写寄存器供下一迭代 fresh 拷贝，不污染本迭代闭包捕获的 cell）。
+        // 循环变量每迭代新分配一个 cell，update 写寄存器供其拷入，不污染本迭代
+        // 闭包捕获的 cell（机制见 `compile_ctx.rs` 的 `register_update_names` 字段文档）。
         if ctx.register_update_names.iter().any(|n| n == name) {
             if let Some(reg) = ctx.scopes.symbols.lookup_any(name) {
                 let op = match (update.operator, update.prefix) {
@@ -751,7 +753,8 @@ impl Emitter {
             };
             ctx.inst(Inst::new(op, Operand::Reg(var_reg), Operand::Reg(result_reg), Operand::Reg(result_reg)));
             if is_tier {
-                // 顶层已声明 var 自增/自减：新值落全局对象属性（A 侧单一真值）。
+                // 顶层已声明 var 自增/自减：新值写入全局对象属性（顶层 var 的唯一存储，
+                // 引擎侧不保留镜像副本）。
                 self.emit_tier_global_write(name, var_reg, ctx);
             } else if is_implicit {
                 self.emit_implicit_global_write(name, var_reg, ctx);