docs: explain Tessera modules and execution flows in Chinese

src/render/native_visual.rs

@@ -1,3 +1,6 @@
+//! 让原生组件也通过 Endor 的 measure/arrange/paint 协议被调用。
+//! 将 Constraints、Size、Bounds 与 PaintCommand 在托管值和 Rust 值之间转换；原生方法与源覆盖方法共用调用契约。
+//!
 //! Native visual protocol entry points. Values are ordinary managed Endor
 //! objects; geometry is scoped to a live occurrence, never stored on a Block.
 use crate::{
@@ -12,9 +15,11 @@ use endor_core::{
     NativeContext, NativeResult, ObjectRef, ObjectStore, Value, Vm, VmError,
 };
 
+/// 统一构造本模块的参数错误，让调用方停止处理无效输入。
 fn invalid(message: &'static str) -> VmError {
     VmError::InvalidArgument(message)
 }
+/// 从源值中提取并检查托管对象身份，错误类型沿 VM 错误返回。
 fn object(value: &Value) -> Result<ObjectRef, VmError> {
     if let Value::Object(object) = value {
         Ok(*object)
@@ -22,6 +27,7 @@ fn object(value: &Value) -> Result<ObjectRef, VmError> {
         Err(invalid("visual protocol requires objects"))
     }
 }
+/// 在源 Value 与所需数值表示之间转换，并沿用本调用的有限值/范围检查。
 pub(crate) fn number(
     cx: &NativeContext<'_>,
     object: ObjectRef,
@@ -40,9 +46,11 @@ pub(crate) fn number(
     }
     Ok(value)
 }
+/// 将原生布局计算结果封装为协议需要的托管 Value。
 pub(crate) fn value(value: f32) -> Value {
     Value::Number((value as f64).into())
 }
+/// 新建指定名义类型的托管记录，并逐项设置字段，作为视觉协议的结果返回。
 pub(crate) fn record(
     cx: &mut NativeContext<'_>,
     desktop: ObjectRef,
@@ -56,6 +64,7 @@ pub(crate) fn record(
     }
     Ok(object)
 }
+/// 在约束提供的视口内执行原生布局，从根出现提取宽高，再按协议约束限制结果。
 fn size(node: &crate::ui_bridge::UiNode, constraints: [f32; 4]) -> Result<Size, VmError> {
     let frame = layout::frame_with_viewport(
         node,
@@ -75,6 +84,7 @@ fn size(node: &crate::ui_bridge::UiNode, constraints: [f32; 4]) -> Result<Size,
     })
 }
 #[derive(Debug, Clone, Copy)]
+/// 该原生能力的查询/操作分类，方法包装用它选择具体实现。
 enum Query {
     Measure,
     Arrange,
@@ -82,12 +92,14 @@ enum Query {
     HitTest,
 }
 #[derive(Debug)]
+/// 保存 owner、签名或操作枚举的原生方法适配器，统一由 VM 调用。
 struct Method {
     query: Query,
     desktop: ObjectRef,
     signature: CallSignature,
 }
 /// Only this actual implementation can use the matching intrinsic fast path.
+/// 判断方法是否为匹配协议的宿主原生实现，决定能否安全使用快速路径。
 pub(crate) fn is_intrinsic(
     store: &ObjectStore,
     function: ObjectRef,
@@ -122,13 +134,16 @@ pub(crate) fn is_intrinsic(
 }
 
 impl NativeCallable for Method {
+    /// 给出参数与返回值的托管类型契约；实际操作在 invoke 中执行。
     fn signature(&self) -> Option<CallSignature> {
         Some(self.signature.clone())
     }
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(3))
     }
 
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let [owner, context, input] = args else {
             return Err(invalid("visual method expects a Mount and an input value"));
@@ -352,15 +367,18 @@ impl NativeCallable for Method {
 }
 
 #[derive(Debug)]
+/// Point 的矩形/圆形命中辅助方法，保存结果类型和具体几何判定种类。
 struct PointMethod {
     expected: ObjectRef,
     circle: bool,
     signature: CallSignature,
 }
 impl NativeCallable for PointMethod {
+    /// 给出参数与返回值的托管类型契约；实际操作在 invoke 中执行。
     fn signature(&self) -> Option<CallSignature> {
         Some(self.signature.clone())
     }
+    /// 声明宿主可调用对象接受的参数个数，供 VM 在执行前检查。
     fn arity(&self) -> Option<endor_core::CallArity> {
         Some(endor_core::CallArity::exact(if self.circle {
             4
@@ -369,6 +387,7 @@ impl NativeCallable for PointMethod {
         }))
     }
 
+    /// VM 调入本宿主能力的入口；按所属操作解码参数并返回托管值或后续调用。
     fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
         let Some(Value::Object(point)) = args.first() else {
             return Err(invalid("Point method requires a Point"));
@@ -419,6 +438,7 @@ impl NativeCallable for PointMethod {
     }
 }
 
+/// 把本模块的类型、方法或能力注册到所属运行时上下文。
 pub fn install(
     vm: &mut Vm,
     roots: &mut Vec<ObjectRef>,