docs: 逐模块细化中文逻辑注释并覆盖测试与示例

This commit is contained in:
2026-11-12 10:31:35 +08:00
parent d29a1be329
commit cd23e70db1
123 changed files with 2664 additions and 249 deletions
+27 -7
View File
@@ -13,13 +13,14 @@ use endor_core::{
/// 验证 hitTest 返回的是 Bool,避免把任意真值隐式当成命中。
struct Boolean;
impl NativeCallable for Boolean {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收 hitTest 返回的唯一值,交给 invoke 严格检查 Bool。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 只接受真正的 Bool 并原样返回;数字或对象不能以宿主真值规则替代源协议契约。
fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 协议要求明确 Bool;拒绝数字、对象等“真值”,使用户实现错误立即暴露。
let [Value::Bool(value)] = args else {
return Err(VmError::InvalidArgument("hitTest must return Bool"));
};
@@ -30,13 +31,14 @@ impl NativeCallable for Boolean {
/// 比较按下与释放的选择结果,只有同一目标才能继续点击分发。
struct SameTarget;
impl NativeCallable for SameTarget {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收按下与释放两次命中选择的结果。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(2))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 仅当两结果为同一 Mount 对象才返回目标,否则返回 Nil;共享 Block 的不同出现位置也不能合成点击。
fn invoke(&self, _: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 比较的是实际出现 Mount 的身份;即使共享同一个 Block,不同出现之间拖动也不构成点击。
let value = match args {
[Value::Object(first), Value::Object(second)] if first == second => {
Value::Object(*first)
@@ -53,6 +55,7 @@ fn code(
constants: Vec<Value>,
layout: CodeLayout,
) -> Result<ObjectRef, VmError> {
// 校验并编码指令,同时设置诊断位置;独立空 globals 避免驱动依赖业务全局命名空间。
let code = EndorCode::from_instructions(&instructions, constants, layout)?.with_location(
"<pointer hitTest>",
"<tessera>",
@@ -76,11 +79,13 @@ fn selector(
))?;
let mut instructions = Vec::new();
let mut constants = vec![Value::Object(validate)];
// 候选按绘制顺序提供,逆序使最上层先参与测试;弱引用失效视为过期输入错误。
for weak in candidates.iter().rev() {
let mount = cx
.upgrade(*weak)?
.ok_or(VmError::InvalidArgument("pointer Mount expired"))?;
let target = cx.store().payload::<Mount>(mount, "Mount")?.clone();
// 先排除已卸载、非交互和几何不命中的出现,避免为明显无效候选构造源调用。
if !target.mounted
|| !target.geometry.interactive
|| !target
@@ -91,14 +96,17 @@ fn selector(
}
let geometry = &target.geometry;
let point = crate::geometry::Point::new(point[0], point[1]);
// 把投影坐标反算到节点逻辑空间;不可逆/无效投影没有可用于 hitTest 的局部坐标。
let Some(point) = geometry.logical_point(point) else {
continue;
};
// 源 Point 以节点左上为原点;这里再次验证范围,避免变换后的点落到节点盒子之外。
let x = point.x - geometry.x;
let y = point.y - geometry.y;
if x < 0.0 || y < 0.0 || x > geometry.width || y > geometry.height {
continue;
}
// 依据真实 Block 的名义类型解析 hitTest,不用原生矩形命中替代源协议。
let definition = cx
.store()
.type_of(target.block)?
@@ -111,6 +119,7 @@ fn selector(
attach_desktop_type(cx, local, "Point", desktop)?;
cx.set_attr(local, "x", Value::Number((x as f64).into()))?;
cx.set_attr(local, "y", Value::Number((y as f64).into()))?;
// 每个候选占四个常量:协议函数、Block、Mount、局部 Point;索引供下面字节码复用。
let start = constants.len() as u32;
constants.extend([
Value::Object(function),
@@ -118,12 +127,16 @@ fn selector(
Value::Object(mount),
Value::Object(local),
]);
// false 分支只跳过“加载本 Mount 并返回”两条指令。按编码宽度计算,
// 常量索引大到需要扩展操作数时仍能跳到下一候选。
let skip = (Instruction::encode_all(&[
Instruction::new(Opcode::LoadConst, start + 2),
Instruction::simple(Opcode::ReturnValue),
])?
.len()
/ 2) as u32;
// 先调用 hitTest(block, mount, local),再把结果传给 validate。
// true 立即返回本 Mount;false 继续下一个候选,实现透明区域向下穿透。
instructions.extend([
Instruction::new(Opcode::LoadConst, 0),
Instruction::simple(Opcode::PushNull),
@@ -139,6 +152,7 @@ fn selector(
Instruction::simple(Opcode::ReturnValue),
]);
}
// 所有候选均未命中时显式返回 Nil;不会把最后一个 false 当作选择结果。
let end = constants.len() as u32;
constants.push(Value::Nil);
instructions.extend([
@@ -156,13 +170,14 @@ struct Prepare {
desktop: ObjectRef,
}
impl NativeCallable for Prepare {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 候选、按下点和释放点已保存于适配器,无需外部实参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 为按下/释放各建立只读选择器,把两次结果放入同一 VM 调用序列,再交 SameTarget 比较实际出现身份。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
// 按下和释放分别构造选择器,但都在本次只读执行内调用,使用同一预算域。
let down = selector(cx, &self.candidates, self.press, self.desktop)?;
let up = selector(cx, &self.candidates, self.release, self.desktop)?;
let compare = cx.allocate(ContextNativeFunction::new(
@@ -170,6 +185,7 @@ impl NativeCallable for Prepare {
SameTarget,
vec![],
))?;
// 两次选择结果先存入局部槽,再作为两个实参交给 SameTarget;局部槽也保留中间结果生命周期。
let instructions = vec![
Instruction::new(Opcode::LoadConst, 0),
Instruction::simple(Opcode::PushNull),
@@ -199,6 +215,7 @@ impl NativeCallable for Prepare {
..CodeLayout::default()
},
)?;
// 把执行权交回 VM 运行驱动,不在宿主里递归开启另一次 VM 调用。
Ok(NativeResult::Invoke {
function: driver,
arguments: vec![],
@@ -206,7 +223,7 @@ impl NativeCallable for Prepare {
}
}
/// Returned Mount owns one root. No-hit and mismatched targets return None.
/// 解析输入所指向的实际目标,避免把包装身份与底层数据混淆。
/// 在一次有界只读调用中分别选择按下与释放目标;仅二者为同一 Mount 时返回其拥有根。
pub fn resolve(
vm: &mut Vm,
desktop: ObjectRef,
@@ -214,6 +231,7 @@ pub fn resolve(
press: [f32; 2],
release: [f32; 2],
) -> anyhow::Result<Option<ObjectRef>> {
// 显式 captures 保活 desktop;候选列表仍是弱引用,不因等待选择而保活全部旧 Mount。
let prepare = vm.allocate(ContextNativeFunction::new(
"prepare pointer hitTest",
Prepare {
@@ -232,9 +250,11 @@ pub fn resolve(
max_instructions: 1_000_000,
},
);
// 先保存调用结果再释放入口根,因此 VM 返回错误时也能完成入口清理。
vm.release(prepare)?;
let (value, _) = result.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
match value {
// 成功返回的 Mount 仍拥有一次根引用,交由调用方使用并释放;None 不转移任何对象根。
Value::Object(mount) => Ok(Some(mount)),
Value::Nil => Ok(None),
value => {