docs: kernel 小文件注释改写

crates/oxide_kernel/src/code_forge.rs

@@ -1,2 +1,3 @@
-/// compiled bytecode cache：按编译后的 module 缓存字节码，避免重复编译。
+/// 字节码缓存（自 `oxide_code_cache` 再导出）：按编译后的 module 缓存字节码，
+/// 避免重复编译。
 pub use oxide_code_cache::CodeForge;

crates/oxide_kernel/src/kernel_log.rs

@@ -1,3 +1,6 @@
+//! kernel 子系统日志宏：`kernel_error!`/`kernel_warn!`/`kernel_info!`/`kernel_debug!`/
+//! `kernel_trace!`，target 为 `oxide::kernel`。
+
 #[macro_export]
 macro_rules! kernel_error {
     ($($arg:tt)*) => {

crates/oxide_kernel/src/lib.rs

@@ -1,4 +1,4 @@
-#![doc = "OxideJS - Shared kernel (CodeForge, ShapeForge, PropForge, StringForge, BuiltinWorld)"]
+#![doc = "OxideJS 共享内核：所有 VM 实例共享的只读缓存（CodeForge/ShapeForge/PropForge/StringForge）与内置对象 world（BuiltinWorld）的构造和重建。"]
 //!
 //! 运行时共享内核层：所有 VM 实例共享的只读缓存（code cache、hidden class /
 //! shape store、属性模板、字符串 intern 表）以及内置对象（builtin world）的
@@ -7,7 +7,7 @@
 
 /// 内置运行时对象（Object/Array/... 及各自原型）的构造与重建。
 pub mod builtin;
-/// compiled bytecode cache 的再导出（来自 `oxide_code_cache`）。
+/// 字节码缓存的再导出（来自 `oxide_code_cache`）。
 pub mod code_forge;
 /// kernel 核心：配置、共享缓存入口（[`KernelCore`]）与 per-session 状态。
 pub mod kernel;

crates/oxide_kernel/src/shape_forge.rs

@@ -31,7 +31,7 @@ pub struct Shape {
 /// 共享隐藏类存储。
 ///
 /// 并发模型：
-/// - `shapes` 为 append-mostly，受 `RwLock` 保护。
+/// - `shapes` 以追加为主，受 `RwLock` 保护。
 /// - `transitions` 是以 `(parent_shape, property_name)` 为键的分片 `DashMap`。
 /// - `positions` 缓存 `(shape_id, prop_name) → slot`，供 O(1) 重复查询。
 /// - 分片数固定，保证跨机器的争用行为可复现，不依赖 DashMap 的 CPU 相关默认值。
@@ -245,8 +245,8 @@ mod tests {
     use super::*;
     use std::sync::Barrier;
 
-    /// overflow 态复位钉：曾触发 overflow 后清空，overflow 标志与映射须一并清空，
-    /// 后续 make_shape 从新空间取小 id（而非旧 overflow 映射 id）。
+    /// overflow 态复位：曾触发 overflow 后 `clear_transient` 须一并清空 overflow
+    /// 标志与 overflow 映射，后续 `make_shape` 从新空间取小 id 而非旧映射 id。
     #[test]
     fn clear_transient_resets_overflow_state() {
         let forge = ShapeForge::new();

crates/oxide_kernel/src/string_forge.rs

@@ -7,8 +7,7 @@ use rustc_hash::FxHasher;
 
 use crate::{kernel_debug, kernel_trace};
 
-/// 完整 64 位内容哈希。替代旧的 16 位 `hash16`，使 interner 的
-/// hash→候选表碰撞风险可忽略。
+/// 完整 64 位内容哈希。interner 的 hash→候选表碰撞风险可忽略。
 fn hash64(s: &str) -> u64 {
     let mut h = FxHasher::default();
     s.hash(&mut h);
@@ -239,15 +238,15 @@ pub fn source_escape_to_key(text: &str) -> String {
 /// 一条 intern 过的键。`data` 是泄漏的 `&'static str`——永久键从不释放
 /// （按设计 append-only），所以泄漏即存储模型，而非 bug。键 id 与 64 位
 /// 哈希经 `DashMap` 的哈希键→候选 id 表寻址，条目自身不存哈希。
-/// `#[repr(C)]` 把布局钉为连续（指针, 长度）：字段序与对齐由 repr(C)
-/// 保证（非 pack 保证），16B 由下方尺寸断言钉死。
+/// 布局以 `repr(C)` 固定为连续 16 字节（指针, 长度）；下方 `size_of`
+/// 断言使布局变更编译失败。
 #[repr(C)]
 #[derive(Clone, Copy)]
 struct PermEntry {
     data: &'static str,
 }
 
-// 布局钉：repr(C) 保证连续 16B；布局漂移即编译失败。
+// `repr(C)` 布局固定为连续 16B；布局变更时此断言编译失败。
 const _: () = assert!(std::mem::size_of::<PermEntry>() == 16);
 
 /// 所有 VM 共享的 append-only、永不移动、读无锁的键 interner。
@@ -318,8 +317,8 @@ impl PermInterner {
         (id, hash)
     }
 
-    /// 以零克隆解析键 id 的文本。返回的 `&'static str`
-    /// 在整个程序生命周期内有效（键从不释放）。
+    /// 以 `&'static str` 返回键 id 的文本，不分配；返回引用在整个程序
+    /// 生命周期内有效（键从不释放）。
     pub fn lookup(&self, id: u32) -> Option<&'static str> {
         let entries = self.entries.read().unwrap();
         entries.get(id as usize).map(|e| e.data)
@@ -431,7 +430,7 @@ pub fn small_int_ptr(n: u32) -> Option<*const JsString> {
 /// typeof 结果文本表（下标见 [`typeof_string_ptr`]），进程生命周期内不释放。
 const TYPEOF_TEXTS: [&str; 8] = ["undefined", "object", "boolean", "number", "string", "symbol", "bigint", "function"];
 
-/// typeof 结果永久 `JsString` 指针表：typeof 是高频分支产出（typeof_ops 每迭代 4 次），
+/// typeof 结果永久 `JsString` 指针表：typeof 运算符是高频产出路径，
 /// 复用静态表免每次 session 分配与 interner 锁查。泄漏面严格有界：8 条目 ≈ 数百字节。
 static TYPEOF_TABLE: [OnceLock<StringPtr>; 8] = [const { OnceLock::new() }; 8];