docs: explain Tessera modules and execution flows in Chinese

src/shell/developer_tools/console.rs

@@ -1,5 +1,9 @@
+//! 绘制 Console 输入、结果历史和对应命中区域。
+//! 这里消费工具状态并生成显示列表；用户程序的编译执行由提交路径和 worker 完成。
+//!
 use super::*;
 
+/// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
 pub(super) fn build(
     p: &mut Painter,
     state: &mut DeveloperToolsState,

src/shell/developer_tools/network.rs

@@ -1,5 +1,9 @@
+//! 绘制已观察到的 HTTP 活动、请求列表与详情。
+//! 筛选、选择和滚动是工具视图状态；展示一条请求不会重发该请求。
+//!
 use super::*;
 
+/// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
 pub(super) fn build(
     p: &mut Painter,
     state: &mut DeveloperToolsState,

src/shell/developer_tools/painter.rs

@@ -1,16 +1,23 @@
+//! 开发工具画面的绘制辅助：文字行、按钮、分隔线和滚动条。
+//! 绘制命令与可交互区域同步登记，保证屏幕上的管理控件能用同一几何命中。
+//!
 use super::*;
 
+/// 开发工具的绘制助手，把布局结果写入同帧显示列表。
 pub(super) struct Painter {
     pub(super) ui: Ui<Action>,
     pub(super) layout: DeveloperToolsLayout,
 }
 impl Painter {
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn fill(&mut self, r: Rect, c: Color) {
         self.ui.fill(r, c);
     }
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn label(&mut self, x: f32, y: f32, value: &str, c: Color, code: bool) {
         self.ui.label(x, y, value, c, code);
     }
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn button(&mut self, r: Rect, label: &str, action: Action, active: bool) {
         let role = match action {
             Action::Follow | Action::Snapshot | Action::Cloud => Role::Toggle,
@@ -19,14 +26,17 @@ impl Painter {
         self.ui
             .button(r, action, Button::new(label).selected(active).role(role));
     }
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn enabled_button(&mut self, r: Rect, label: &str, action: Action, enabled: bool) {
         self.ui
             .button(r, action, Button::new(label).enabled(enabled));
     }
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn split(&mut self, r: Rect, kind: Split) {
         // Paint and register splitters after all pane content, in one overlay pass.
         self.layout.splits.push((r, kind));
     }
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn lines(
         &mut self,
         area: Rect,
@@ -132,6 +142,7 @@ impl Painter {
         self.scrollbar(area, region, false, s.y, content_h);
         self.scrollbar(area, region, true, s.x, content_w);
     }
+    /// 绘制对应管理界面原语，并按控件需要同步登记命中和滚动区域。
     pub(super) fn scrollbar(
         &mut self,
         r: Rect,
@@ -170,6 +181,7 @@ impl Painter {
     }
 }
 #[derive(Clone)]
+/// 一行可绘制、可关联源码位置的工具文本。
 pub(super) struct Line {
     pub(super) value: String,
     pub(super) color: Color,
@@ -178,11 +190,13 @@ pub(super) struct Line {
     pub(super) action: Option<Action>,
 }
 #[derive(Clone, Copy)]
+/// 管理画面内分隔条方向/位置描述。
 pub(super) enum Divider {
     Accent,
     Neutral,
 }
 impl Line {
+    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
     pub(super) fn new(value: impl Into<String>, color: Color) -> Self {
         Self {
             value: value.into(),
@@ -193,6 +207,7 @@ impl Line {
         }
     }
 }
+/// 按行绘制工具文本，返回后续布局需要的占用范围。
 pub(super) fn multiline(out: &mut Vec<Line>, value: &str, color: Color) {
     out.extend(
         value
@@ -201,6 +216,7 @@ pub(super) fn multiline(out: &mut Vec<Line>, value: &str, color: Color) {
             .map(|s| Line::new(s, color)),
     );
 }
+/// 把一条 Console 结果投影为可滚动、可选择的文字画面。
 pub(super) fn console_result(out: &mut Vec<Line>, body: &str, color: Color) {
     if let Ok(value) = serde_json::from_str::<serde_json::Value>(body) {
         if value["execution"] == "repl" {
@@ -263,6 +279,7 @@ pub(super) fn console_result(out: &mut Vec<Line>, body: &str, color: Color) {
     }
     multiline(out, body, color);
 }
+/// 将代码层次展开为工具可绘制的行数据，保留节点与源范围关联。
 pub(super) fn flatten<'a>(node: &'a CodeNode, depth: usize, out: &mut Vec<(usize, &'a CodeNode)>) {
     out.push((depth, node));
     for child in &node.children {
@@ -270,6 +287,7 @@ pub(super) fn flatten<'a>(node: &'a CodeNode, depth: usize, out: &mut Vec<(usize
     }
 }
 
+/// 绘制选中请求的头部、正文预览与响应信息，不重新执行该请求。
 pub(super) fn request_details(out: &mut Vec<Line>, r: &Exchange) {
     multiline(
         out,

src/shell/developer_tools/selection.rs

@@ -1,3 +1,6 @@
+//! 多行文本选择和光标导航。选择端点映射到合法字符边界，避免把 UTF-8 字节中间当成一个字符。
+//! 工具只保留当前文本行和选择范围；复制操作取得的是所选内容，不是整份运行时状态。
+//!
 //! Read-only, grapheme-aware source selection, independent of console editing.
 use crate::{
     geometry::Point,
@@ -6,6 +9,7 @@ use crate::{
 use unicode_segmentation::UnicodeSegmentation;
 
 #[derive(Debug, Default)]
+/// 行文本、锚点与选择端点，既供鼠标拖选也供键盘导航使用。
 pub(super) struct SourceSelection {
     lines: Vec<String>,
     anchor: (usize, usize),
@@ -13,6 +17,7 @@ pub(super) struct SourceSelection {
     pub dragging: bool,
 }
 impl SourceSelection {
+    /// 替换可选择文本行，并把旧选择限制在新文本仍有效的位置。
     pub fn set_lines(&mut self, lines: &[String]) {
         if self.lines != lines {
             self.lines = lines.to_vec();
@@ -21,6 +26,7 @@ impl SourceSelection {
             self.dragging = false;
         }
     }
+    /// 把工具指针位置换算成合法行号与文本字符边界。
     fn locate(p: Point, origin: Point, lines: &[String]) -> (usize, usize) {
         let row = (((p.y - origin.y) / super::ROW).floor().max(0.0) as usize)
             .min(lines.len().saturating_sub(1));
@@ -39,14 +45,17 @@ impl SourceSelection {
         }
         (row, byte)
     }
+    /// 在指针位置建立文本选择锚点，开始一次拖动选择。
     pub fn begin(&mut self, p: Point, origin: Point, lines: &[String]) {
         self.anchor = Self::locate(p, origin, lines);
         self.end = self.anchor;
         self.dragging = true;
     }
+    /// 保持原锚点，随指针更新选择另一端。
     pub fn extend(&mut self, p: Point, origin: Point, lines: &[String]) {
         self.end = Self::locate(p, origin, lines);
     }
+    /// 用键盘移动文本选择端点，按扩展模式决定是否保留锚点。
     pub fn navigate(
         &mut self,
         key: &winit::keyboard::NamedKey,
@@ -109,6 +118,7 @@ impl SourceSelection {
         }
         Some(row)
     }
+    /// 返回排序后的有效选择范围，隐藏拖动方向差异。
     fn range(&self, all: bool) -> ((usize, usize), (usize, usize)) {
         if all {
             return (
@@ -121,6 +131,7 @@ impl SourceSelection {
         }
         (self.anchor.min(self.end), self.anchor.max(self.end))
     }
+    /// 拼接当前选择范围内的实际文本，保持多行换行与 UTF-8 边界。
     pub fn text(&self, all: bool) -> String {
         let (a, b) = self.range(all);
         self.lines
@@ -135,6 +146,7 @@ impl SourceSelection {
             .collect::<Vec<_>>()
             .join("\n")
     }
+    /// 取得某行的可见选择片段，供高亮绘制复用。
     pub fn span(&self, row: usize, all: bool, lines: &[String]) -> Option<(f32, f32)> {
         let (a, b) = self.range(all);
         if row < a.0 || row > b.0 || a == b {

src/shell/developer_tools/settings.rs

@@ -1,5 +1,9 @@
+//! 绘制宿主设置页面和主题选择区域。
+//! 这里只投影当前设置和交互目标，平台原生窗口行为由对应系统适配层负责。
+//!
 use super::*;
 
+/// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
 pub(super) fn build(p: &mut Painter, state: &mut DeveloperToolsState, viewport: Rect) {
     let x = viewport.x;
     let w = viewport.width;

src/shell/developer_tools/sources.rs

@@ -1,5 +1,9 @@
+//! 绘制 AST、当前源码快照和云文件视图。
+//! 当前快照是发布源的只读投影；云文件 provider 的可用性与打开状态分别反馈，不把查看代码当成执行代码。
+//!
 use super::*;
 
+/// 根据当前输入构造本模块的派生结果，具体的验证与资源边界见函数内步骤。
 pub(super) fn build(
     p: &mut Painter,
     state: &mut DeveloperToolsState,