csh
c69278283f
Generate TSL API Markdown from YAML or JSON into a configurable project scope.\nAdd file and directory lint modes, tags-aware indexing, and keyword search across tags and descriptions.\nBundle the toolkit through the playbook build and sync workflows.
207 lines
6.1 KiB
Markdown
207 lines
6.1 KiB
Markdown
# 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)
|