csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📦 deps(tsl): sync tsl-playbook from aa8a3e73

Browse Source 
Source-Commit: aa8a3e73a8
This commit is contained in:
ci[bot]
2026-07-30 01:23:00 +00:00
parent 80357f4bc5
commit 7c9a23746f
3 changed files with 1608 additions and 297 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/tsl-codegen/STANDARD.md
+86 -101
View File
@@ -24,22 +24,19 @@
- [function](#function-2)
- [class](#class-2)
- [unit](#unit-2)
- [录入格式（用户必看）](#录入格式用户必看)
- [录入文件格式](#录入文件格式)
- [yaml](#yaml)
- [json](#json)
- [统一 API 索引](#统一-api-索引)
## 基本原则
- markdown 是唯一存储源
- yaml/json 用于生成 markdown
- tsf 源码文档可以转换为 json 或 yaml 录入稿，再由同一生成流程产出 markdown
- 发布的 API 文档使用本标准定义的 markdown 存储格式
- tsf 源码文档、yaml/json 录入数据与 markdown 的字段映射以本标准为准
- 一个录入文件对应一个 markdown 叶子页；录入根固定为
`module`、`path`、`declarations`
- `declarations` 是非空有序列表，function、class、unit 可以按输入顺序混合
- 生成器写入 markdown 前必须使用仓库锁定版本的 Prettier 统一格式
- 转换器允许生成描述或类型不完整的草稿；生成器严格校验，不发布不完整录入稿
- function 调用签名由维护者或转换器提供；工具不推断 API 语义
- `declarations` 是非空有序列表，function、class、unit 可以混合；列表顺序即文档顺序
- function 调用签名只记录显式名称和参数名，不包含类型、默认值或语义推断内容
- API 标题的反引号内只写名称或调用签名，不写 function、class、property 等声明术语
- 每个 API 用独立的 `声明：...` 行记录声明种类
- 描述紧跟声明行；tags 是描述的检索补充，位于完整描述之后
@@ -56,11 +53,10 @@ function、class、unit 都是同级的顶级声明，可以出现在同一页
种类写在自身正文的 `声明：function|class|unit` 行中。
目录承担领域或模块分组，叶子页承担 API 主题分组，H2 承担顶级声明分组。markdown
不要求一个 class 对应一个 md；多个独立 class TSF 的对外声明可以进入同一叶子页，
也可以在内容过长或主题不同时拆到同一目录下的多个叶子页。例如
不要求一个 class 对应一个 md；多个独立 class 声明可以进入同一叶子页，也可以在
内容过长或主题不同时拆到同一目录下的多个叶子页。例如
`OpenXmlAttribute` 和 `OpenXmlElement` 可以作为两个 H2 同处
`officexml/openxml/elements.md`。每个 TSF 文件对应一个对外顶级声明，一个 markdown
叶子页可以收录多个对外顶级声明。
`officexml/openxml/elements.md`。一个 markdown 叶子页可以收录多个对外顶级声明。
顶级声明和成员都按文档顺序存储，不按名称、种类或可见性重新排序。每个顶级声明
按以下共同顺序开始：
@@ -161,7 +157,7 @@ function 重载和跨声明种类同名允许。
#### 示例代码
- 每个示例以“范例NN：说明”开头，编号按出现顺序自动生成并至少保留两位
- 每个示例以“范例NN：说明”开头，编号按出现顺序排列并至少保留两位
- 代码围栏使用 `tsl`
- 一个代码围栏只放一个独立示例
- 字符串使用直引号 `'` 或 `"`
@@ -247,7 +243,7 @@ return demoFn(src, 0);
3. class 描述，必填
4. tags，可选；位于完整描述之后
5. `父类：BaseClass`，可选；多父类按声明顺序列出
6. class 成员，按源码顺序书写
6. class 成员，按声明顺序书写
#### 成员标题与正文
@@ -411,7 +407,7 @@ unit function 的参数取值/示例使用 H4，interface class function 的参
2. `声明：unit`
3. unit 描述，必填
4. tags，可选；位于完整描述之后
5. interface direct member，按源码顺序书写
5. interface direct member，按声明顺序书写
#### 成员标题与正文
@@ -423,8 +419,8 @@ H3 direct member 标题只写名称或调用签名。标题后的声明行只允
- interface class：`声明：class`
每个 direct member 都按“标题、声明行、描述、tags、成员数据”的共同顺序开始。
unit direct member 都来自 interface，因此正文不重复写 public；统一索引把其
visibility 规范化为 `public`。unit function 复用顶级 function 格式并要求返回
unit direct member 都来自 interface，visibility 固定为 `public`，正文不重复记录。
unit function 复用顶级 function 格式并要求返回
类型，var 必须写类型，const 必须写值。interface class 的 H4 成员复用顶级
class 的成员格式，并显式写 `可见性：public|protected`。
@@ -490,7 +486,7 @@ class 的成员格式，并显式写 `可见性：public|protected`。
### 综合示例
同一叶子页可以按录入顺序混合三种顶级声明。以下 API 仅用于说明存储格式，不代表
同一叶子页可以按文档顺序混合三种顶级声明。以下 API 仅用于说明存储格式，不代表
真实 TSL API：
````markdown
@@ -571,30 +567,29 @@ return ParseOpenXml('<root/>');
## tsf 源码文档格式
tsf 主要使用 `function`、`unit` 和 `type` 三种顶层组织方式。本标准按这三种方式
分别定义源码文档格式。转换器可以一次接收任意混合的 TSF 输入；每个文件贡献一个
对外顶级声明，并严格保持命令行输入顺序。
分别定义源码文档格式。每个 tsf 源码文档对应一个对外顶级声明。
### function
独立顶层 `function` 可以在源码中记录录入数据所需的函数级内容。签名、参数类型、
默认参数和返回类型直接读取源码声明。
独立顶层 `function` 可以在源码中记录函数级文档。签名、参数类型、默认参数和返回
类型由源码声明提供，描述、标签、参数说明、枚举值和示例由文档块提供。
- 一个 tsf 文件只记录第一个主函数；文件中的后续辅助函数不进入录入数据
- 顶层 `procedure` 不按 `function` 格式处理
- 多个 tsf 可以与 class/unit TSF 混合生成同一个 json/yaml 录入文件；页面级
`module` 和 `path` 在转换时统一提供，不写进单个函数的注释
- 一个 function tsf 文件只以第一个顶层 function 作为对外主函数；后续辅助函数不属于
该文件的对外文档
- 顶层 `procedure` 不在本节规定的 function 文档格式范围内
- `module` 和 `path` 是页面级录入字段，不属于单个函数的文档块
#### 文档块位置
文档块必须是主函数 `begin` 之后的第一段非空内容，并且位于任何可执行语句、
编译指令或其他注释之前
文档块由连续的 `///` 行组成。允许按照函数体缩进；解析时忽略 `///` 之前的空白，
并移除 `///` 及其后的一个可选空格。遇到第一行非 `///` 内容时，文档块结束；函数体
后续位置的注释是普通注释
文档块由连续的 `///` 行组成，并允许按照函数体缩进。`///` 之前的空白以及其后的
一个可选空格不属于文档内容。遇到第一行非 `///` 内容时，文档块结束；函数体后续
位置的注释是普通注释
TSL 解释器将 `///` 作为普通的 `//` 行注释；第三个 `/` 是 codegen 用来识别文档行的
标记
TSL 解释器将 `///` 作为普通的 `//` 行注释；本标准使用第三个 `/` 区分文档行与普通
注释
#### 文档块结构
@@ -609,7 +604,7 @@ TSL 解释器将 `///` 作为普通的 `//` 行注释；第三个 `/` 是 codege
空的 `///` 行可以在多行函数描述或示例中保留空行。指令名固定为小写；未知指令、
重复的 `@tags:`/`@returns:`、同一参数重复的 `@param:`/`@values:`，以及不符合上述
顺序的指令均视为错误。`@example:` 可以重复，`@output:` 在同一示例组内最多出现
顺序的指令均不符合本标准。`@example:` 可以重复，`@output:` 在同一示例组内最多出现
一次。
| 写法 | 必填 | json 映射 | 规则 |
@@ -623,36 +618,35 @@ TSL 解释器将 `///` 作为普通的 `//` 行注释；第三个 `/` 是 codege
| 示例代码 | 示例组内 | `declarations[].examples[].code` | 内容行额外缩进两个空格；至少包含一个非空代码行 |
| `@output:` | 否 | `declarations[].examples[].output` | 原始输出额外缩进两个空格；存在时不得为空 |
`@param:` 和 `@values:` 中的参数名与函数声明大小写无关地匹配，json 使用函数声明中的
参数拼写。
`@param:` 和 `@values:` 中的参数名与函数声明大小写无关地匹配；映射后的参数名保留
函数声明中的拼写。
#### 字段来源与映射
以下字段由主函数声明以及必要的文档指令确定：
| tsf 声明内容 | json 字段 | 转换规则 |
| -------------- | ---------------------------------- | --------------------------------------------------- |
| 函数名 | `declarations[].name` | 保留声明名称 |
| 函数名和参数名 | `declarations[].signature` | 规范化为只含名称的调用形式，不复制类型或默认值 |
| 参数类型 | `declarations[].params[].type` | 保留声明中的类型 |
| 参数默认值 | `declarations[].params[].optional` | 存在默认值时写入 `true`，默认表达式不另建 json 字段 |
| 返回类型 | `declarations[].returns` | 读取声明和 `@returns:`，按下述规则合并 |
| tsf 声明内容 | json 字段 | 映射规则 |
| -------------- | ---------------------------------- | ------------------------------------------------- |
| 函数名 | `declarations[].name` | 保留声明名称 |
| 函数名和参数名 | `declarations[].signature` | 规范化为只含名称的调用形式，不复制类型或默认值 |
| 参数类型 | `declarations[].params[].type` | 保留声明中的类型 |
| 参数默认值 | `declarations[].params[].optional` | 存在默认值时为 `true`，默认表达式不另建 json 字段 |
| 返回类型 | `declarations[].returns` | 取自声明和 `@returns:`，按下述规则合并 |
要直接得到可生成 markdown 的完整录入数据，函数必须显式声明每个参数的类型，为每个
参数提供非空的 `@param:`，并通过函数声明或 `@returns:` 提供返回类型。缺少这些内容
时只能得到待手工完善的录入稿。
完整录入数据必须包含每个参数的显式类型和非空说明，并通过函数声明或 `@returns:`
提供返回类型。
可选参数的说明仍应写清默认值含义；`optional: true` 只表达该参数可以省略。
返回类型按以下规则合并：
- 只有函数声明时，使用声明中的拼写
- 只有 `@returns:` 时，去除首尾空白后使用指令中的拼写
- 两处同时存在时，转换器使用与函数声明相同的词法规则拆分类型，忽略 token 之间的
空白，并按 TSL 标识符大小写无关的规则比较标识符 token；其他 token 必须一致。
校验通过后使用声明中的拼写，校验失败则定位 `@returns:` 行、报错并停止转换
- 两处都不存在时，录入稿中的 `returns` 为空，不能直接生成 markdown
- 两处同时存在时，使用相同的词法规则拆分类型，忽略 token 之间的空白，并按 TSL
标识符大小写无关的规则比较标识符 token；其他 token 必须一致。两处类型必须匹配，
映射后使用声明中的拼写
- 两处都不存在时，不满足顶级 function 的 `returns` 必填要求
转换器只校验类型的词法结构，不判断类型别名等语义等价。
本标准只定义类型的词法一致性，不定义类型别名等语义等价关系。
#### 枚举值表
@@ -673,10 +667,10 @@ TSL 解释器将 `///` 作为普通的 `//` 行注释；第三个 `/` 是 codege
- 不接受数组、对象或 json `null`
- 值和说明以值后的第一个分隔冒号分开；说明不得为空
- 保留枚举项的声明顺序
- 同一参数最多有一个非空值表，重复值视为错误；不同 json 类型的值不视为重复，
- 同一参数最多有一个非空值表，不允许重复值；不同 json 类型的值不视为重复，
例如数字 `1` 与字符串 `"1"` 是两个值
- `@values:` 引用的参数必须存在
- 转换器不推断枚举值是否与参数类型兼容，该语义由 tsf 作者负责
- tsf 作者必须保证枚举值与参数类型在语义上兼容
#### 示例组
@@ -685,20 +679,20 @@ TSL 解释器将 `///` 作为普通的 `//` 行注释；第三个 `/` 是 codege
`@example:` 开始新的示例组。第一个示例组出现后，不得再写参数、返回类型等其他函数
级指令。
转换时移除代码和输出的两个结构缩进，保留其余空白和换行。示例说明、代码和输出
分别映射为 `examples[].desc`、`examples[].code` 和 `examples[].output`。`desc` 与
映射到录入数据时，移除代码和输出的两个结构缩进，保留其余空白和换行。示例说明、
代码和输出分别映射为 `examples[].desc`、`examples[].code` 和 `examples[].output`。`desc` 与
`code` 必填且非空；`output` 可选，但出现时必须包含至少一个非空行。示例顺序保持
不变。
`code` 只记录示例源码，不得包含标准输出标记 `// 输出：`。`output` 只记录原始输出，
不写 `//` 注释标记。生成 markdown 时：
不写 `//` 注释标记。映射到 markdown 时：
- 所有示例共用一个 `### 示例` 标题
- 每项按顺序生成“范例01：说明”“范例02：说明”
- 每项生成一个独立的 `tsl` 代码块
- 每项按顺序写为“范例01：说明”“范例02：说明”
- 每项使用一个独立的 `tsl` 代码块
- 没有 `output` 时，代码块只包含 `code`
- 单行 `output` 在代码末尾生成 `// 输出：<值>`
- 多行 `output` 先生成 `// 输出：`，再为每个输出行添加 `//` 和一个空格；空输出行生成
- 单行 `output` 在代码末尾写为 `// 输出：<值>`
- 多行 `output` 先写 `// 输出：`，再为每个输出行添加 `//` 和一个空格；空输出行使用
单独的 `//`
#### 完整 tsf 示例
@@ -950,33 +944,32 @@ end;
### unit
unit 只接受包含显式 `interface`、`implementation` 并以 `end.` 结束的完整形态。
unit 名称必须与文件名大小写无关地一致；简写 unit 明确报错。
本标准的 unit 源码文档采用包含显式 `interface`、`implementation` 并以 `end.` 结束的
完整形态；简写 unit 不在本标准范围内。unit 名称必须与文件名大小写无关地一致。
unit 文档块位于 `unit Name;` 之后、`interface` 之前，只允许描述和可选
`@tags:`。转换器按源码顺序收录 interface 中的 function、var、const 和 class；
`uses` 只表示依赖，不进入 API。interface class 完整复用独立 class 的成员规则，
但 interface 中的所有 class 都进入文档。受支持区域中无法绑定到 unit 或 interface
成员的 `///` 文档块按原始行号报错。
`@tags:`。对外文档按声明顺序包含 interface 中的 function、var、const 和 class；
`uses` 只表示依赖，不属于 API。interface class 完整复用独立 class 的成员规则，
interface 中的所有 class 均属于对外文档。每个 `///` 文档块必须绑定到 unit 或
interface 成员。
进入 implementation 后停止收集 API；其中的函数、类、变量、常量和 `///` 文档块
全部忽略。interface 中的 procedure 和非 class type 不支持，必须在声明行报错，
不能静默遗漏。interface function 复用 function 文档指令并要求最终返回类型；
var/const 只允许描述和可选 `@tags:`，且一项一条声明。
implementation 中的函数、类、变量、常量和 `///` 文档块不属于对外文档。interface
中的 procedure 和非 class type 不在本标准范围内。interface function 复用 function
文档指令并要求返回类型；var/const 只允许描述和可选 `@tags:`，且一项一条声明。
## 录入数据结构
一个录入文件对应一个 markdown 叶子页。录入根只允许 `module`、`path`、
`declarations`。`declarations` 必须是非空有序列表，function、class、unit 可以
任意混合，生成器严格保持数组顺序。
任意混合；数组顺序即 markdown 中的 H2 声明顺序。
顶层字段：
| 字段 | 必填 | 说明 |
| -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `module` | 是 | markdown 一级标题内容；不是目录名或文件名。例如 `module: 示例 / 数组` 生成 `# 示例 / 数组` |
| `path` | 是 | 目标 markdown 在 scope 目录下的相对路径，包含子目录和文件名，使用 `/` 分隔且不含 `.md` 后缀。例如 `path: base/example` 在默认 `project` scope 下生成 `references/codegen/project/base/example.md` |
| `declarations` | 是 | 非空顶级声明列表；每项由 `kind` 判别并要求 `name`，按数组顺序生成 H2 |
| 字段 | 必填 | 说明 |
| -------------- | ---- | -------------------------------------------------------------------------------------------------------------------- |
| `module` | 是 | markdown 一级标题内容；不是目录名或文件名。例如 `module: 示例 / 数组` 对应 `# 示例 / 数组` |
| `path` | 是 | markdown 在所属 scope 下的相对路径，使用 `/` 分隔且不含 `.md` 后缀。例如 `path: base/example` 对应 `base/example.md` |
| `declarations` | 是 | 非空顶级声明列表；每项由 `kind` 判别并要求 `name`，数组顺序即 H2 顺序 |
### function
@@ -986,22 +979,22 @@ var/const 只允许描述和可选 `@tags:`，且一项一条声明。
| ----------- | ------ | ------------------------------------------------------ |
| `kind` | 是 | 固定为 `function` |
| `name` | 是 | function 简单名称；必须与 `signature` 中的名称一致 |
| `signature` | 是 | 维护者提供的调用签名 |
| `signature` | 是 | 只包含名称和参数名的调用签名 |
| `desc` | 是 | 函数描述，可包含多行 |
| `tags` | 否 | 检索关键词列表；推荐填写，有助于更准确地识别和检索函数 |
| `params` | 有参时 | 参数列表；无参函数省略 |
| `returns` | 是 | 返回类型 |
| `examples` | 否 | 示例列表；按顺序生成独立的 TSL 代码块 |
| `examples` | 否 | 示例列表；按顺序映射为独立的 TSL 代码块 |
参数字段：
| 字段 | 必填 | 说明 |
| ---------- | ---- | ------------------------------- |
| `name` | 是 | 参数名，与签名一致 |
| `type` | 是 | 参数类型 |
| `desc` | 是 | 参数说明 |
| `optional` | 否 | `true` 时自动添加 `可选。` 前缀 |
| `values` | 否 | 枚举值列表，生成参数取值说明 |
| 字段 | 必填 | 说明 |
| ---------- | ---- | ------------------------------------------------------ |
| `name` | 是 | 参数名，与签名一致 |
| `type` | 是 | 参数类型 |
| `desc` | 是 | 参数说明 |
| `optional` | 否 | `true` 表示可选参数；markdown 参数说明以 `可选。` 开头 |
| `values` | 否 | 枚举值列表，对应参数取值说明 |
`values` 每项包含：
@@ -1012,11 +1005,11 @@ var/const 只允许描述和可选 `@tags:`，且一项一条声明。
`examples` 每项包含：
| 字段 | 必填 | 说明 |
| -------- | ---- | ---------------------------------------------------- |
| `desc` | 是 | 示例场景说明；生成“范例NN：说明” |
| `code` | 是 | 不含代码围栏和标准输出注释的 TSL 代码 |
| `output` | 否 | 原始输出；生成器按单行或多行规则转换为 `//` 输出注释 |
| 字段 | 必填 | 说明 |
| -------- | ---- | ---------------------------------------------- |
| `desc` | 是 | 示例场景说明；对应“范例NN：说明” |
| `code` | 是 | 不含代码围栏和标准输出注释的 TSL 代码 |
| `output` | 否 | 原始输出；按单行或多行规则映射为 `//` 输出注释 |
### class
@@ -1045,8 +1038,8 @@ class 对象字段：
`kind: method` 对象不使用 `static` 字段；class function 由 `binding: class` 唯一
表达。`value` 的存在性与真假值分开判断，因此数字 `0` 和布尔值 `false` 都是合法
常量值。
这里的 `method` 是录入结构内部用于归一化实例 function 和 class function 的 kind，
不会写进 markdown 标题或 `声明：...` 行。
这里的 `method` 是录入结构内部用于统一表达实例 function 和 class function 的 kind，
不对应 markdown 标题或 `声明：...` 行中的声明值。
### unit
@@ -1062,13 +1055,11 @@ class 对象字段：
录入数据不保存 unit 的 `uses`、implementation、initialization 或 finalization。
## 录入格式（用户必看）
## 录入文件格式
### yaml
yaml 适合包含多行示例的页面。解析 yaml 需要安装 `pyyaml`
注意：
yaml 录入文件应符合以下规则：
- `examples[].code` 和多行 `examples[].output` 使用 `|` 块标量
- 参数名 `...` 必须加引号
@@ -1078,9 +1069,7 @@ yaml 适合包含多行示例的页面。解析 yaml 需要安装 `pyyaml`
### json
json 使用 Python 标准库解析，无额外依赖
注意：
json 录入文件应符合以下规则：
- json 不支持注释
- 多行 `examples[].code` 和 `examples[].output` 使用 `\n`
@@ -1130,7 +1119,3 @@ name scope module signature page anchor tags summary kind binding visibility own
例如 class function `Widget.Create` 的 owner 是 `Widget`；unit interface class
function `DemoUnit.Document.Save` 的 owner 是 `DemoUnit.Document`。重载共享
`qualified_name`，由 `signature` 和唯一的 `page#anchor` 区分。
lookup 的 `--name` 同时精确匹配简单名称与 `qualified_name`，比较大小写不敏感。
简单成员名会返回所有 owner 下的同名 API；完全限定名称用于缩小到指定 class/unit。
`--kw` 还会搜索 kind、binding、visibility、owner 和 qualified_name。