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
+13 -1
View File
@@ -3,7 +3,7 @@
//!
use super::*;
/// 根据当前输入构造本模块的派生结果,具体的验证与资源边界见函数内步骤。
/// 根据云文件/当前快照模式构建左右两栏,展示文件或 AST 选择,并生成只读源码行和跳转动作。
pub(super) fn build(
p: &mut Painter,
state: &mut DeveloperToolsState,
@@ -12,6 +12,7 @@ pub(super) fn build(
) {
let x = viewport.x;
let w = viewport.width;
// width 在本函数表示右边界坐标,w 才是视口宽度;用于计算右侧源码区域和按钮位置。
let width = viewport.x + viewport.width;
let bottom = viewport.height - 22.0;
@@ -28,6 +29,7 @@ pub(super) fn build(
Action::Cloud,
state.cloud,
);
// 两种数据源分开投影:云模式用 provider 的 files/opened,快照模式只读已发布文档 source/root。
if state.cloud {
p.button(
Rect::new(width - 92.0, 32.0, 88.0, 29.0),
@@ -35,6 +37,7 @@ pub(super) fn build(
Action::CloudRefresh,
false,
);
// 树宽至少 120,通常为右侧内容保留 180;窄窗口仍保持树最小宽,交由绘制裁剪处理。
let tree = state.tree_width.clamp(120.0, (w - 180.0).max(120.0));
let code_x = x + tree + 2.0;
p.label(x + 10.0, 69.0, "CLOUD FILES", MUTED, false);
@@ -44,6 +47,7 @@ pub(super) fn build(
.iter()
.map(|file| {
let mut l = Line::new(&file.path, TEXT);
// 动作传递 provider 的不透明文件 ID,显示路径不参与本地磁盘读取或代码执行。
l.action = Some(Action::CloudOpen(file.id.clone()));
l
})
@@ -57,6 +61,7 @@ pub(super) fn build(
);
p.split(Rect::new(x + tree, 63.0, 1.0, bottom - 63.0), Split::Tree);
let mut source_lines = Vec::new();
// 成功打开的云文本逐行加显示行号;这里不替换 doc.source,也不触发程序热重载。
if let Some(source) = &state.cloud_sources.opened {
p.label(code_x + 10.0, 69.0, &source.path, MUTED, false);
for (i, line) in source.code.split('\n').enumerate() {
@@ -69,6 +74,7 @@ pub(super) fn build(
MUTED,
);
}
// provider 错误附在当前源码下方;即使读取失败仍可展示上次成功打开的内容。
if !state.cloud_sources.error.is_empty() {
source_lines.push(Line::new(&state.cloud_sources.error, ERROR));
}
@@ -91,6 +97,7 @@ pub(super) fn build(
if doc
.root
.as_ref()
// REPL 文档展示为交互记录,普通脚本展示为 app.main.endor;仅改变标题,不合成另一份源码。
.is_some_and(|root| root.kind == "repl-session")
{
"Console transcript"
@@ -105,6 +112,7 @@ pub(super) fn build(
let mut tree_lines = Vec::new();
if let Some(root) = &doc.root {
let mut flat = Vec::new();
// 将发布 AST 展平成带深度的行;行动作保存节点稳定 ID 与起始行,用于选择并跳到对应代码。
flatten(root, 0, &mut flat);
for (depth, n) in flat {
let mut l = Line::new(format!("{}{} {}", " ".repeat(depth), n.kind, n.name), TEXT);
@@ -123,23 +131,27 @@ pub(super) fn build(
false,
);
p.split(Rect::new(x + tree, 63.0, 1.0, bottom - 63.0), Split::Tree);
// 每次重绘按当前文档查节点,旧选择 ID 若已不存在则不高亮,避免沿用旧 AST 行范围。
let selected = state
.selected_node_id
.as_deref()
.and_then(|id| doc.node(id));
let code_lines = doc
.source
// 仅显示投影统一 CRLF 并把 Tab 展开为四空格;原始文档文本保持不变。
.replace("\r\n", "\n")
.split('\n')
.enumerate()
.map(|(i, s)| {
let mut l = Line::new(format!("{:>5} {}", i + 1, s.replace('\t', " ")), TEXT);
// i 是零基行号,AST 行号是一基;条件等价于 start_line <= i+1 <= end_line。
l.selected = selected.is_some_and(|n| i + 1 >= n.start_line && i < n.end_line);
l
})
.collect::<Vec<_>>();
p.lines(
Rect::new(code_x, 92.0, width - code_x, bottom - 92.0),
// 源码区与 AST 树各自保存滚动位置,选择节点并不把树文本误当作源码内容。
Region::Source,
&code_lines,
state,