# 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` 代码块，可选

### 标签

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

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

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

### 参数表

参数表固定为三列：

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

规则：

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

### 参数取值

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

```markdown
**mode 取值**

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

### 返回类型

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

```markdown
返回：array
```

### 示例代码

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

多行输出示例：

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

### 完整条目示例

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

````markdown
## `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)
```
````

无参函数省略参数表：

````markdown
## `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](examples/example.yaml)

## JSON 录入格式

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

注意：

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

完整例子：[examples/example.json](examples/example.json)