Files

T

ci[bot] 9fedb2cf7f 📦 deps(tsl): sync tsl-playbook from 49e6dadc

Source-Commit: 49e6dadc60

2026-07-20 01:42:42 +00:00

6.1 KiB

Raw Blame History

TSL 函数文档标准

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

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

基本原则

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

Markdown 存储格式

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

## \函数签名``
，可选
函数描述，必填；首个非空内容必须是描述
参数表，有参数时必填
参数取值说明，可选
返回：类型
### 示例 和 tsl 代码块，可选

参数表

参数表固定为三列：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `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

6.1 KiB Raw Blame History