From 3dceaf71fd3953cdec201f28cebe781f48815291 Mon Sep 17 00:00:00 2001 From: csh Date: Tue, 6 Jan 2026 10:34:34 +0800 Subject: [PATCH] :memo: docs(tsl): clarify tsf-only top-level rules and type annotations --- docs/tsl/code_style.md | 6 ++++-- docs/tsl/naming.md | 10 +++++----- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/tsl/code_style.md b/docs/tsl/code_style.md index 735fd75..dcbb3be 100644 --- a/docs/tsl/code_style.md +++ b/docs/tsl/code_style.md @@ -17,7 +17,8 @@ ### 1.2 文件名与顶层声明（硬约束） -- TSL 语法要求：每个文件只能有一个顶层声明，且文件基名必须与顶层声明同名。 +- TSL 语法要求（仅 `.tsf`）：每个 `.tsf` 文件只能有一个顶层声明，且文件基名必须与顶层声明同名。 +- `.tsl` 允许直接写语句，不要求顶层声明；文件名不强制，但建议清晰可检索。 - 推荐文件名使用 `PascalCase` 以提升检索与协作一致性；扩展名按类型使用 `.tsl`/`.tsf`（两者都属于 TSL 源文件，风格规则一致）。 - 详细约束与命名细则见 `docs/tsl/naming.md`。 @@ -177,7 +178,8 @@ end; ### 4.2 函数设计 - 签名尽量自解释：对外 API 的参数/返回值建议显式写类型注解；并用注释写清契约（可复用 3.2 的模板）。 -- 无返回值函数显式标注返回类型为 `void`。 +- 类型注解不支持 `xxx.xxx` 形式；使用单一类型名。 +- 无返回值函数显式标注返回类型为 `void`；`create`/`destroy` 作为构造/析构函数不写返回类型。 ```tsl function Func(a: string; b: ClassName): void; diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md index 48371da..5adabe2 100644 --- a/docs/tsl/naming.md +++ b/docs/tsl/naming.md @@ -32,8 +32,8 @@ ## 3. 类型命名（Type Names） -TSL 的顶层声明只有三种：`class`、`unit`、`function`。 -因此文件基名必须与顶层声明同名（见“4. 文件命名与顶层声明”）。 +TSL 的顶层声明只有三种：`class`、`unit`、`function`（仅适用于 `.tsf`）。 +因此 `.tsf` 文件基名必须与顶层声明同名（见“4. 文件命名与顶层声明”）。 - **类（class）与单元（unit）**使用 `PascalCase`，不带下划线；名称应为名词/名词短语（通常单数），避免动词开头。 - 不推荐 `*Unit` 作为 `unit` 的后缀（`unit` 本身已表达语义）；需要表达用途时，可使用 `*Shared`/`*Common`/`*Enums` 等更具体后缀（按团队约定）。 @@ -42,13 +42,13 @@ TSL 的顶层声明只有三种：`class`、`unit`、`function`。 ## 4. 文件命名与顶层声明（File Names） -TSL 的语法要求：每个文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。 +TSL 的语法要求（仅 `.tsf`）：每个 `.tsf` 文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。 - 顶层声明可能是 `class`、`unit` 或 `function`（见类型命名）。 - `.tsf` 代码文件：用于库/模块等“顶层声明”的承载文件；顶层声明可为 `class`/`unit`/`function`，文件基名需与之同名。 -- `.tsl` 脚本文件：用于入口/编排层；顶层声明只能是 `function`，因此文件基名 = 顶层函数名；可复用逻辑应下沉到 `.tsf`（见 `docs/tsl/code_style.md`）。 +- `.tsl` 脚本文件：用于入口/编排层；允许直接写语句（如 `a := 1; echo a;`），不要求顶层声明，也不强制文件基名与函数名一致；可复用逻辑应下沉到 `.tsf`（见 `docs/tsl/code_style.md`）。 - 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。 -- **硬规则**：重命名顶层声明时必须同步重命名文件基名，否则语法/加载规则无法识别；批量重命名可参考 `$bulk-refactor-workflow`。 +- **硬规则（仅 `.tsf`）**：重命名顶层声明时必须同步重命名文件基名，否则语法/加载规则无法识别；批量重命名可参考 `$bulk-refactor-workflow`。 命名建议：