docs: 逐模块细化中文逻辑注释并覆盖测试与示例
This commit is contained in:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user