playbook/tools/tsl-codegen/STANDARD.md

TSL 函数文档标准

本文件是 TSL codegen 函数文档的唯一标准，包含 Markdown 存储格式和 YAML/JSON 录入格式

适用范围：references/codegen/**/*.md 中的函数条目

基本原则

• Markdown 是唯一存储源
• YAML/JSON 用于生成 Markdown
• 函数签名由维护者提供；工具原样输出，不校正签名内容
• 示例输出必须全部写成 // 注释，不得把裸结果写成 TSL 语句
• 一个 tsl 代码块只放一个独立示例

Markdown 存储格式

每个函数条目按以下顺序书写：

1. ## \函数签名``
2. <!-- tags: 关键词1 关键词2 -->，可选
3. 函数描述，必填；首个非空内容必须是描述
4. 参数表，有参数时必填
5. 参数取值说明，可选
6. 返回：类型
7. ### 示例 和 tsl 代码块，可选

标签

标签紧跟函数签名，用空格分隔检索关键词：

<!-- tags: 数组 排序 去重 -->

没有关键词时删除整行，不保留空标签

参数表

参数表固定为三列：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `src` | array | 待处理数组 |

规则：

• 参数名必须与函数签名一致
• 必填参数说明直接写用途
• 可选参数说明以 可选。 开头，并说明默认值
• 多类型使用 \|，例如 nil\|array
• 变参使用 ... 作为参数名

参数取值

枚举参数在参数表之后、返回类型之前列出：

**mode 取值**

- `0` — 原样返回
- `1` — 去重

返回类型

每个函数必须包含非空返回类型：

返回：array

示例代码

• 代码围栏使用 tsl
• 字符串使用直引号 ' 或 "
• 注释使用 //，不使用 (* *)
• 每条语句保留分号
• 单行输出写成 // 输出：<值>
• 多行输出第一行写 // 输出：，后续每一行输出都以 // 开头

多行输出示例：

return demoLines();
// 输出：
// 第一行
// 第二行

完整条目示例

以下函数仅用于说明文档格式，不代表真实 TSL API

## `demoFn(src, mode, factor, ...)`
<!-- tags: 示例 数组 -->

按指定模式处理数组并返回结果

| 参数     | 类型       | 说明                              |
| -------- | ---------- | --------------------------------- |
| `src`    | array      | 待处理数组                        |
| `mode`   | integer    | 处理模式，取值见下。              |
| `factor` | float      | 可选。默认 1.0，结果乘以该系数。  |
| `...`    | nil\|array | 可选。需要追加处理的其他数组。    |

**mode 取值**

- `0` — 原样返回
- `1` — 去重

返回：array

### 示例

```tsl
src := array(1, 1, 2);
return demoFn(src, 1, 2.0);
// 输出：array(2,4)
```

无参函数省略参数表：

## `demoNow()`

返回示例值

返回：integer

### 示例

```tsl
return demoNow();
// 输出：1
```

录入数据结构

一个录入文件对应一个 Markdown 叶子页

顶层字段：

字段	必填	说明
module	是	Markdown 一级标题内容；不是目录名或文件名。例如 module: 示例 / 数组 生成 # 示例 / 数组
path	是	目标 Markdown 在 scope 目录下的相对路径，包含子目录和文件名，使用 / 分隔且不含 .md 后缀。例如 path: base/example 在默认 project scope 下生成 references/codegen/project/base/example.md
functions	是	非空函数列表

函数字段：

字段	必填	说明
signature	是	维护者提供的完整函数签名
desc	是	函数描述，可包含多行
tags	否	检索关键词列表；推荐填写，有助于更准确地识别和检索函数
params	有参时	参数列表；无参函数省略
returns	是	返回类型
example	否	不含代码围栏的 TSL 示例

参数字段：

字段	必填	说明
name	是	参数名，与签名一致
type	是	参数类型
desc	是	参数说明
optional	否	true 时自动添加 可选。 前缀
values	否	枚举值列表，生成参数取值说明

values 每项包含：

字段	必填	说明
value	是	枚举值
desc	是	枚举含义

YAML 录入格式

YAML 适合包含多行示例的页面。解析 YAML 需要安装 pyyaml

注意：

• example 使用 | 块标量
• 参数名 ... 必须加引号
• nil|array 可直接作为普通字符串值

完整例子：examples/example.yaml

JSON 录入格式

JSON 使用 Python 标准库解析，无额外依赖

注意：

• JSON 不支持注释
• 多行示例使用 \n
• 字符串内部的双引号使用 \"
• 结构标点必须使用半角字符

完整例子：examples/example.json