feat(tsl-syntax-reference): harden retrieval contracts

Add stable section IDs, structural and routing regressions, quickstart consistency checks, and CI enforcement.

BREAKING CHANGE: replace heading-derived Section IDs with explicit syntax-NN-NNN identifiers.
This commit is contained in:
csh
2026-07-31 10:05:15 +08:00
parent 21e688a436
commit 736d1a8ad7
30 changed files with 1635 additions and 137 deletions
@@ -4,10 +4,14 @@
## 本篇职责
<!-- section-id: syntax-17-001 -->
回答“外部 DLL 声明、原生函数指针包装、C 回调和多线程调用有哪些文档明确写法”。本页只覆盖系统交互能力,普通 TSL 函数的定义与调用不在本页收口。
## 核心规则
<!-- section-id: syntax-17-002 -->
- 外部函数声明的文档明确形态是 `function Name(...): Type; stdcall|cdecl; external "dll" [name "symbol"];`
- 当 TSL 函数名和 DLL 导出名一致时,`name "symbol"` 可以省略。
- Windows 示例默认显式写调用约定;不要把省略调用约定当成跨平台默认规则。
@@ -21,8 +25,12 @@
## 可直接照写示例
<!-- section-id: syntax-17-003 -->
### 最小 `external` 声明
<!-- section-id: syntax-17-004 -->
<!-- tags: 调外部函数, 声明外部函数, 绑 dll 函数, 导入系统函数 -->
代码块身份:可直接照写示例
@@ -99,6 +107,8 @@ function TickCdecl(): int64; cdecl; external "kernel32.dll" name "GetTickCount64
### `procedure external`
<!-- section-id: syntax-17-005 -->
<!-- tags: 外部过程, 无返回值的外部函数, 调系统 API -->
代码块身份:可直接照写示例
@@ -120,6 +130,8 @@ procedure SleepMs(ms: integer); stdcall; external "kernel32.dll" name "Sleep";
### 原生函数指针包装
<!-- section-id: syntax-17-006 -->
<!-- tags: LoadLibrary, 拿函数地址, 动态加载, GetProcAddress -->
代码块身份:可直接照写示例
@@ -143,6 +155,8 @@ function GetProcAddress(module_handle: pointer; proc_name: string): pointer; std
### DLL 名的文档边界
<!-- section-id: syntax-17-007 -->
<!-- tags: dll 名写在哪, 库名怎么给, 常量放路径 -->
类常量字符串:
@@ -181,6 +195,8 @@ function TickFromExpr(): int64; stdcall; external "kernel32"$"."$"dll" name "Get
### `makeInstance`
<!-- section-id: syntax-17-008 -->
<!-- tags: 回调函数, 把 TSL 函数给 C 用, 生成函数实例 -->
代码块身份:可直接照写示例
@@ -205,6 +221,8 @@ end;
### 线程模式最小正例
<!-- section-id: syntax-17-009 -->
<!-- tags: 开线程, 多线程, 并发执行, 后台跑 -->
代码块身份:可直接照写示例
@@ -238,6 +256,8 @@ end;
## 默认生成模板
<!-- section-id: syntax-17-010 -->
DLL 引入的最小默认骨架如下:
代码块身份:可直接照写示例
@@ -250,6 +270,8 @@ function Tick64Alias(): int64; stdcall; external "kernel32.dll" name "GetTickCou
## 禁止项
<!-- section-id: syntax-17-011 -->
-`external` 的 DLL 名直接写成字符串拼接表达式。
- 省略了外部函数的参数类型或返回类型。
-`makeInstance(...)` 生成的结果默认写成普通函数名直调,而不是先包装或用 `##f(...)`