docs: explain Tessera modules and execution flows in Chinese

src/shell/system_ui/widgets.rs

@@ -1,3 +1,6 @@
+//! 用统一主题绘制宿主管理控件，并同步注册交互目标。
+//! 每个控件的图形、角色、启用状态和 action 一起登记，绘制几何与命中几何保持一致。
+//!
 use super::{
     Axis, Interaction, Role, Target, VisualState, WidgetId,
     theme::{self, Theme},
@@ -9,6 +12,7 @@ use crate::{
 };
 use std::hash::Hash;
 
+/// 一次按钮绘制的借用描述，包括显示、角色和启用/选中状态。
 pub struct Button<'a> {
     pub label: &'a str,
     pub selected: bool,
@@ -16,6 +20,7 @@ pub struct Button<'a> {
     pub role: Role,
 }
 impl<'a> Button<'a> {
+    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
     pub fn new(label: &'a str) -> Self {
         Self {
             label,
@@ -24,20 +29,24 @@ impl<'a> Button<'a> {
             role: Role::Button,
         }
     }
+    /// 设置当前控件描述的选择、启用或角色信息，供后续绘制和目标登记使用。
     pub fn selected(mut self, value: bool) -> Self {
         self.selected = value;
         self
     }
+    /// 设置当前控件描述的选择、启用或角色信息，供后续绘制和目标登记使用。
     pub fn enabled(mut self, value: bool) -> Self {
         self.enabled = value;
         self
     }
+    /// 设置当前控件描述的选择、启用或角色信息，供后续绘制和目标登记使用。
     pub fn role(mut self, value: Role) -> Self {
         self.role = value;
         self
     }
 }
 
+/// 本帧宿主控件绘制上下文，共同拥有显示列表与交互目标登记入口。
 pub struct Ui<A> {
     pub list: DisplayList,
     pub targets: Vec<Target<A>>,
@@ -45,6 +54,7 @@ pub struct Ui<A> {
     interaction: Interaction,
 }
 impl<A: Hash> Ui<A> {
+    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
     pub fn new(theme: Theme, interaction: Interaction) -> Self {
         Self {
             list: DisplayList::default(),
@@ -53,6 +63,7 @@ impl<A: Hash> Ui<A> {
             interaction,
         }
     }
+    /// 使用当前主题绘制控件填充、轮廓或文字原语。
     pub fn fill(&mut self, r: Rect, color: Color) {
         self.list.push(DrawCommand::FillRoundedRect {
             rect: r,
@@ -60,6 +71,7 @@ impl<A: Hash> Ui<A> {
             color,
         });
     }
+    /// 使用当前主题绘制控件填充、轮廓或文字原语。
     fn outline(&mut self, r: Rect, color: Color, width: f32) {
         self.list.push(DrawCommand::StrokeRoundedRect {
             rect: Rect::new(
@@ -73,6 +85,7 @@ impl<A: Hash> Ui<A> {
             color,
         });
     }
+    /// 使用当前主题绘制控件填充、轮廓或文字原语。
     pub fn label(&mut self, x: f32, y: f32, value: &str, color: Color, code: bool) {
         self.list.push(DrawCommand::Text {
             origin: Point::new(x, y),
@@ -89,6 +102,7 @@ impl<A: Hash> Ui<A> {
             color,
         });
     }
+    /// 把控件身份、几何、角色、启用状态和 action 一起加入本帧交互目标。
     fn register(
         &mut self,
         id: WidgetId,
@@ -108,6 +122,7 @@ impl<A: Hash> Ui<A> {
         });
         response
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     fn surface(&mut self, rect: Rect, s: VisualState, base: Option<Color>) {
         let color = if !s.enabled {
             base
@@ -127,6 +142,7 @@ impl<A: Hash> Ui<A> {
             self.outline(rect, self.theme.accent, 1.5);
         }
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn button(&mut self, rect: Rect, action: A, button: Button<'_>) -> VisualState {
         let id = WidgetId::new(&action);
         let s = self.register(
@@ -168,6 +184,7 @@ impl<A: Hash> Ui<A> {
         self.list.push(DrawCommand::PopClip);
         s
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn text_field(&mut self, rect: Rect, action: A, focused: bool) {
         let s = self.register(
             WidgetId::new(&action),
@@ -191,6 +208,7 @@ impl<A: Hash> Ui<A> {
         );
     }
     /// A terminal prompt shares its surface with output; its caret is the focus cue.
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn inline_input(&mut self, rect: Rect, action: A) {
         self.register(
             WidgetId::new(&action),
@@ -201,6 +219,7 @@ impl<A: Hash> Ui<A> {
             true,
         );
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn row(&mut self, paint: Rect, hit: Rect, action: A, selected: bool) {
         let s = self.register(
             WidgetId::new(&action),
@@ -212,6 +231,7 @@ impl<A: Hash> Ui<A> {
         );
         self.surface(paint, s, None);
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn swatch(&mut self, rect: Rect, action: A, color: Color, selected: bool) {
         let s = self.register(
             WidgetId::new(&action),
@@ -249,6 +269,7 @@ impl<A: Hash> Ui<A> {
             self.label(rect.x + 10.0, rect.y + 6.0, "✓", theme::BG, false);
         }
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn splitter(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
         let hit = Rect::new(
             rect.x - 3.0,
@@ -273,6 +294,7 @@ impl<A: Hash> Ui<A> {
         };
         self.fill(line, color);
     }
+    /// 绘制对应宿主管理控件，并使用同一矩形注册命中/捕获所需的交互信息。
     pub fn scrollbar(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
         let mut s = self.register(id, rect, Role::Scrollbar(axis), None, false, true);
         s.pressed |= self.interaction.captured(id);