docs: explain Tessera modules and execution flows in Chinese

src/render/text.rs

@@ -1,3 +1,7 @@
+//! 统一字体发现、文字整形、测量与抗锯齿字形绘制。
+//! 测量与绘制使用同一字体系统和样式，避免布局宽度与屏幕文字不一致；中文与其他字符通过字体回退处理。
+//! 整形和字形缓存有数量/字节预算；极端放大采用有界字形 LOD，最终只遍历裁剪区域内的像素。
+//!
 //! Shared font discovery, shaping, measurement and antialiased rasterization.
 use std::{
     collections::HashMap,
@@ -9,12 +13,14 @@ use cosmic_text::{Align, Attrs, Buffer, Family, FontSystem, Metrics, Shaping, Sw
 use crate::display_list::Color;
 
 #[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)]
+/// 界面比例字体与源码等宽字体的选择，不直接指定某个必然安装的系统字体。
 pub enum TextFamily {
     Interface,
     Code,
 }
 
 #[derive(Clone, Copy, Debug)]
+/// 字号、行高和字体类别，测量与绘制必须使用兼容样式。
 pub struct TextStyle {
     pub font_size: f32,
     pub line_height: f32,
@@ -22,6 +28,7 @@ pub struct TextStyle {
 }
 
 impl TextStyle {
+    /// 生成界面文字的基准字号与行高，size 是协议使用的字号倍率。
     pub fn ui(size: u32) -> Self {
         Self {
             font_size: 14.0 * size as f32,
@@ -30,6 +37,7 @@ impl TextStyle {
         }
     }
 
+    /// 生成源码/Console 使用的等宽风格基础尺寸。
     pub fn code() -> Self {
         Self {
             font_size: 13.0,
@@ -38,6 +46,7 @@ impl TextStyle {
         }
     }
 
+    /// 同比缩放字号与行高，保持设备比例变化后的排版比例一致。
     pub fn scaled(self, scale: f32) -> Self {
         Self {
             font_size: self.font_size * scale,
@@ -48,12 +57,14 @@ impl TextStyle {
 }
 
 #[derive(Clone, Copy, Debug)]
+/// 整形后实际占用的逻辑文字尺寸。
 pub struct TextSize {
     pub width: f32,
     pub height: f32,
 }
 
 #[derive(Clone, Hash, PartialEq, Eq)]
+/// 文字整形缓存键，包含文本、样式和可选换行宽度。
 struct TextKey {
     value: String,
     font_size: u32,
@@ -62,11 +73,13 @@ struct TextKey {
     wrap_width: Option<u32>,
 }
 
+/// 已整形 Buffer 与测量结果，后续测量/绘制复用同一布局。
 struct PreparedText {
     buffer: Buffer,
     size: TextSize,
 }
 
+/// 共享字体系统、字形缓存和整形缓存；调用通过全局锁串行访问。
 struct TextEngine {
     fonts: FontSystem,
     code_family: Option<String>,
@@ -76,6 +89,7 @@ struct TextEngine {
 }
 
 impl TextEngine {
+    /// 构造本类型并初始化其状态；资源建立和默认字段以函数体为准。
     fn new() -> Self {
         let mut fonts = FontSystem::new();
         // Select installed, readable families rather than assuming an OS font
@@ -114,10 +128,12 @@ impl TextEngine {
         }
     }
 
+    /// 对不指定换行宽度的文本复用统一整形准备过程。
     fn prepare(&mut self, value: &str, style: TextStyle) -> TextKey {
         self.prepare_width(value, style, None)
     }
 
+    /// 为文本、字体样式和可选换行宽度建立整形缓存，超过缓存预算先清理旧结果。
     fn prepare_width(&mut self, value: &str, style: TextStyle, wrap_width: Option<f32>) -> TextKey {
         let key = TextKey {
             value: value.to_owned(),
@@ -175,17 +191,20 @@ impl TextEngine {
     }
 }
 
+/// 取得全局受锁保护的字体/整形引擎；共享缓存不等于可以并行修改字体状态。
 fn engine() -> &'static Mutex<TextEngine> {
     static ENGINE: OnceLock<Mutex<TextEngine>> = OnceLock::new();
     ENGINE.get_or_init(|| Mutex::new(TextEngine::new()))
 }
 
+/// 返回不受换行宽度约束时的字体整形尺寸。
 pub fn measure(value: &str, style: TextStyle) -> TextSize {
     let mut engine = engine().lock().expect("text engine lock");
     let key = engine.prepare(value, style);
     engine.buffers[&key].size
 }
 
+/// 按可用宽度整形并测量多行高度，供布局与实际段落绘制共用。
 pub fn measure_wrapped(value: &str, style: TextStyle, width: f32) -> TextSize {
     if width <= 0.0 {
         return TextSize {
@@ -201,6 +220,7 @@ pub fn measure_wrapped(value: &str, style: TextStyle, width: f32) -> TextSize {
 /// Rasterize only visible glyph pixels. Large camera zooms use a bounded glyph
 /// bitmap and sample it at the requested size instead of allocating an enormous
 /// font image. Layout and wrapping still use proportionally identical metrics.
+/// 限制字形分辨率并只采样可见像素；保留文字布局比例，同时避免极端相机缩放产生巨型位图。
 pub fn draw_clipped(
     value: &str,
     style: TextStyle,
@@ -300,6 +320,7 @@ pub fn draw_clipped(
 }
 
 /// Fit a single displayed source line without slicing a UTF-8/grapheme cluster.
+/// 按真实字体测量截断到给定宽度，以字素簇边界拼接省略号，避免切开组合字符。
 pub fn fit(value: &str, width: f32, style: TextStyle) -> String {
     use unicode_segmentation::UnicodeSegmentation;