docs: 添加 Rustdoc 注释

crates/oxide_compiler/src/compiler.rs

@@ -1,16 +1,22 @@
+//! 编译入口：`Compiler::compile` 串联 emit 与 lowering。
+
 use oxide_bytecode::module::CompiledModule;
 use oxide_emit::Emitter;
 use oxide_ir::lower::lower;
 
+/// 结构哈希 / 编译模块哈希 re-export（供编译缓存作键）。
 pub use crate::hash::{compiled_module_hash, structural_hash};
 
+/// 编译入口（marker 类型）：无状态，编译状态在 emit/lower 内部。
 pub struct Compiler;
 
 impl Compiler {
+    /// 构造 `Compiler`（无状态，恒返回空实例）。
     pub fn new() -> Self {
         Self
     }
 
+    /// 编译整个 program：AST → IR（`Emitter::emit_program`）→ bytecode（`lower`）。
     pub fn compile(&self, program: &oxide_parser::Program) -> Result<CompiledModule, String> {
         crate::compiler_debug!("compile: starting...");
         let ir = Emitter::new().emit_program(program)?;

crates/oxide_compiler/src/compiler_log.rs

@@ -1,3 +1,5 @@
+//! 编译日志宏：`compiler_error!/warn!/info!/debug!/trace!`，经由 oxide_log 上报。
+
 #[macro_export]
 macro_rules! compiler_error {
     ($($arg:tt)*) => {

crates/oxide_compiler/src/hash/class.rs

@@ -1,3 +1,5 @@
+//! 类相关 AST 节点的结构哈希（ClassElement/ClassExpression 等）。
+
 use super::*;
 
 pub(super) fn hash_class_element(element: &ClassElement, h: &mut rustc_hash::FxHasher, include_binding_names: bool) {

crates/oxide_compiler/src/hash/expression.rs

@@ -1,3 +1,5 @@
+//! 表达式 AST 节点的结构哈希。
+
 use super::*;
 
 pub(super) fn hash_expression(expr: &Expression, h: &mut rustc_hash::FxHasher, include_binding_names: bool) {

crates/oxide_compiler/src/hash/mod.rs

@@ -1,3 +1,9 @@
+//! AST 结构哈希：按语法域（statement/expression/class/...）递归计算
+//! `Program` 的稳定哈希，用作编译缓存键（code cache）。
+//!
+//! `structural_hash` 忽略绑定名（结构相等即可命中），
+//! `compiled_module_hash` 纳入绑定名（精确匹配避免错误复用）。
+
 use oxide_parser::{
     BindingPattern, ChainElement, ClassElement, Expression, ForStatementInit, ObjectPropertyKind, PropertyKey,
     SimpleAssignmentTarget, Statement,
@@ -30,10 +36,12 @@ mod property;
 mod statement;
 mod target;
 
+/// 结构哈希：忽略绑定名的 `Program` 哈希（用于粗粒度缓存命中判断）。
 pub fn structural_hash(program: &oxide_parser::Program) -> u64 {
     hash_program(program, false)
 }
 
+/// 编译模块哈希：纳入绑定名的 `Program` 哈希（用于精确缓存命中判断）。
 pub fn compiled_module_hash(program: &oxide_parser::Program) -> u64 {
     hash_program(program, true)
 }

crates/oxide_compiler/src/hash/property.rs

@@ -1,3 +1,5 @@
+//! 对象属性键/属性类型（PropertyKey/ObjectPropertyKind）的结构哈希。
+
 use super::*;
 
 pub(super) fn hash_property_key(key: &PropertyKey, h: &mut rustc_hash::FxHasher, include_binding_names: bool) {

crates/oxide_compiler/src/hash/statement.rs

@@ -1,3 +1,5 @@
+//! 语句 AST 节点的结构哈希。
+
 use super::*;
 
 pub(super) fn hash_statement(stmt: &Statement, h: &mut rustc_hash::FxHasher, include_binding_names: bool) {

crates/oxide_compiler/src/hash/target.rs

@@ -1,3 +1,5 @@
+//! 赋值目标（SimpleAssignmentTarget）的结构哈希。
+
 use super::*;
 
 pub(super) fn hash_simple_assignment_target(

crates/oxide_compiler/src/lib.rs

@@ -1,4 +1,8 @@
-#![doc = "OxideJS - AST to bytecode compiler"]
+//! oxide_compiler：AST → bytecode 编译入口（编译管线收尾）。
+//!
+//! `Compiler::compile` 串联 `oxide_emit`（AST → IR）与 `oxide_ir::lower`
+//! （IR → bytecode），产出 `CompiledModule`。另有 AST 结构哈希
+//! （`structural_hash` / `compiled_module_hash`）用于编译缓存键。
 
 pub mod compiler;
 pub mod compiler_log;