docs: 添加 Rustdoc 注释

crates/oxide_cli/src/bench/baseline.rs

@@ -1,15 +1,18 @@
 use crate::bench::metrics::MetricCollection;
 
+/// 基准结果集合，持久化到 `benchmark_baseline.json` 用于后续回归对比。
 pub struct Baseline {
     pub entries: Vec<MetricCollection>,
 }
 
 impl Baseline {
+    /// 构造空的基线。
     pub fn empty() -> Self {
         Self { entries: Vec::new() }
     }
 }
 
+/// 一次性能回退：当前指标相对基线的比值超过容差即视为回归。
 pub struct Regression {
     pub metric: String,
     pub test_name: String,
@@ -19,6 +22,7 @@ pub struct Regression {
     pub tolerance: f64,
 }
 
+/// 从 `benchmark_baseline.json` 加载基线；文件不存在时返回空基线。
 pub fn load_baseline() -> Result<Baseline, String> {
     let json_path = "benchmark_baseline.json";
     let data = match std::fs::read_to_string(json_path) {
@@ -33,6 +37,7 @@ pub fn load_baseline() -> Result<Baseline, String> {
     Ok(Baseline { entries })
 }
 
+/// 保存当前结果到 `benchmark_baseline.json` 并生成 Markdown 表格。
 pub fn save_baseline(results: &[MetricCollection]) -> Result<(), String> {
     let json = serde_json::to_string_pretty(results).map_err(|e| format!("Failed to serialize baseline: {}", e))?;
     std::fs::write("benchmark_baseline.json", &json)
@@ -42,6 +47,7 @@ pub fn save_baseline(results: &[MetricCollection]) -> Result<(), String> {
     Ok(())
 }
 
+/// 对比当前结果与基线，返回所有超过各自容差（wall_time 10%、GC 类 50%、其它 20%）的回归项。
 pub fn compare_baseline(current: &[MetricCollection]) -> Vec<Regression> {
     let baseline = match load_baseline() {
         Ok(b) => b,

crates/oxide_cli/src/bench/js_stress.rs

@@ -13,6 +13,8 @@ use crate::bench::metrics::MetricCollection;
 use crate::bench::output::{format_json, format_text_table};
 use crate::bench::BenchConfig;
 
+/// 运行 `tests/stress/` 下全部（或 filter 匹配的）JS 压力测试：
+/// 预热后迭代执行并采集指标，输出 JSON + 表格；必要时保存/对比基线。
 pub fn run_js_stress_bench(config: &BenchConfig, kernel: &Arc<KernelCore>, pool: &Arc<VmPool>) -> ExitCode {
     let mut results: Vec<MetricCollection> = Vec::new();
     let compiler = Compiler::new();

crates/oxide_cli/src/bench/leak_detect.rs

@@ -12,12 +12,15 @@ use crate::bench::metrics::MetricCollection;
 use crate::bench::output::format_json;
 use crate::bench::BenchConfig;
 
+/// 滑动窗口采样器：对 `(iteration, value)` 序列做线性回归，
+/// 当斜率明显为正且拟合度 R² 高时判定为内存泄漏。
 pub struct LeakSampler {
     window: VecDeque<(usize, f64)>,
     window_size: usize,
 }
 
 impl LeakSampler {
+    /// 以给定窗口大小创建采样器。
     pub fn new(window_size: usize) -> Self {
         Self {
             window: VecDeque::new(),
@@ -25,6 +28,7 @@ impl LeakSampler {
         }
     }
 
+    /// 加入一次采样；样本足够且回归显著时返回泄漏判定。
     pub fn add_sample(&mut self, iteration: usize, value: f64) -> Option<LeakVerdict> {
         self.window.push_back((iteration, value));
         if self.window.len() >= self.window_size {
@@ -56,11 +60,14 @@ impl LeakSampler {
     }
 }
 
+/// 泄漏判定的回归结果：线性斜率和拟合优度 R²。
 pub struct LeakVerdict {
     pub slope: f64,
     pub r2: f64,
 }
 
+/// 反复运行固定 JS 脚本，跟踪 session/code-forge/symbol 等内存指标，
+/// 用 `LeakSampler` 回归检测随迭代次数增长的内存占用。
 pub fn run_leak_detect(config: &BenchConfig, kernel: &Arc<KernelCore>, pool: &Arc<VmPool>) -> ExitCode {
     let js =
         "var ITERATIONS = 1000; var obj = {}; for (var i = 0; i < ITERATIONS; i++) { obj['key' + i] = i; } obj['key0']";

crates/oxide_cli/src/bench/metrics.rs

@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 
+/// 单次 benchmark 测试收集的完整指标集（可序列化为 JSON 用于基线持久化）。
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MetricCollection {
     pub test_name: String,
@@ -21,6 +22,7 @@ pub struct MetricCollection {
 }
 
 impl MetricCollection {
+    /// 导出为 `(指标名, 值)` 列表，供回归对比与表格输出遍历。
     pub fn iter_metrics(&self) -> Vec<(&'static str, f64)> {
         vec![
             ("wall_time_us", self.wall_time_us as f64),

crates/oxide_cli/src/bench/mod.rs

@@ -1,8 +1,17 @@
+//! Benchmark 子系统：支持 JS 压力测试（`js`）、Rust 原生 bench（`rust`）
+//! 与内存泄漏检测（`leak`），并附带基线保存/回归对比功能。
+
+/// 基准持久化与回归对比。
 pub mod baseline;
+/// JS 压力测试执行。
 pub mod js_stress;
+/// 内存泄漏检测。
 pub mod leak_detect;
+/// 指标采集结构。
 pub mod metrics;
+/// 结果格式化输出。
 pub mod output;
+/// Rust 原生 benchmark 委托。
 pub mod rust_bench;
 
 use std::process::ExitCode;
@@ -11,6 +20,7 @@ use std::sync::Arc;
 use oxide_kernel::kernel::KernelCore;
 use oxide_vm::vm_pool::VmPool;
 
+/// 一次 bench 运行的全部配置（来自 CLI `bench` 子命令参数）。
 pub struct BenchConfig {
     pub mode: String,
     pub filter: Option<String>,
@@ -21,6 +31,7 @@ pub struct BenchConfig {
     pub leak_check_interval: usize,
 }
 
+/// 按 mode 分派到具体 benchmark 实现（js/rust/leak）。
 pub fn run_benchmarks(config: BenchConfig, kernel: Arc<KernelCore>, pool: Arc<VmPool>) -> ExitCode {
     match config.mode.as_str() {
         "js" => js_stress::run_js_stress_bench(&config, &kernel, &pool),

crates/oxide_cli/src/bench/output.rs

@@ -1,9 +1,11 @@
 use crate::bench::metrics::MetricCollection;
 
+/// 把结果序列化为美观 JSON 字符串。
 pub fn format_json(results: &[MetricCollection]) -> String {
     serde_json::to_string_pretty(results).unwrap_or_else(|e| format!("{{\"error\": \"{}\"}}", e))
 }
 
+/// 把结果格式化为对齐的文本表格（供终端打印）。
 pub fn format_text_table(results: &[MetricCollection]) -> String {
     let mut out = String::new();
     out.push_str(&format!(

crates/oxide_cli/src/bench/rust_bench.rs

@@ -1,3 +1,5 @@
+/// 委托 `cargo bench -p oxide_vm` 运行 Rust 原生 benchmark；
+/// 可选 filter 指定具体 bench 目标。
 pub fn run_rust_bench(filter: Option<&str>) -> std::process::ExitCode {
     let mut cmd = std::process::Command::new("cargo");
     cmd.args(["bench", "-p", "oxide_vm"]);