Files

T

csh aa8a3e73a8 🐛 fix(tsl-codegen): make TSF conversion best effort

Recover recognizable function, procedure, class, and unit structure from
nonstandard TSF input while preserving strict parsing for compliant files.

Keep STANDARD.md limited to published format requirements and cover
recovery paths with regression tests.

2026-07-30 09:20:18 +08:00

37 KiB

Raw Blame History

TSL API 文档标准

本文件是 TSL codegen API 文档的唯一标准，包含 markdown 存储格式、tsf 源码文档格式、yaml/json 录入格式和统一索引格式。

适用范围：references/codegen/**/*.md 中的 function、class 和 unit API。

基本原则

发布的 API 文档使用本标准定义的 markdown 存储格式
tsf 源码文档、yaml/json 录入数据与 markdown 的字段映射以本标准为准
一个录入文件对应一个 markdown 叶子页；录入根固定为 module、path、declarations
declarations 是非空有序列表，function、class、unit 可以混合；列表顺序即文档顺序
function 调用签名只记录显式名称和参数名，不包含类型、默认值或语义推断内容
API 标题的反引号内只写名称或调用签名，不写 function、class、property 等声明术语
每个 API 用独立的 声明：... 行记录声明种类
描述紧跟声明行；tags 是描述的检索补充，位于完整描述之后
描述末尾不写句号
示例输出必须全部写成 // 注释，不得把裸结果写成 TSL 语句
一个 tsl 代码块只放一个独立示例

markdown 存储格式

页面与统一顶级声明

每个 markdown 叶子页使用一个 H1 模块标题，并包含一个或多个 H2 顶级声明。 function、class、unit 都是同级的顶级声明，可以出现在同一页面中；每个 H2 的声明种类写在自身正文的 声明：function|class|unit 行中。

目录承担领域或模块分组，叶子页承担 API 主题分组，H2 承担顶级声明分组。markdown 不要求一个 class 对应一个 md；多个独立 class 声明可以进入同一叶子页，也可以在内容过长或主题不同时拆到同一目录下的多个叶子页。例如 OpenXmlAttribute 和 OpenXmlElement 可以作为两个 H2 同处 officexml/openxml/elements.md。一个 markdown 叶子页可以收录多个对外顶级声明。

顶级声明和成员都按文档顺序存储，不按名称、种类或可见性重新排序。每个顶级声明按以下共同顺序开始：

H2 标题：function 写调用签名，class 和 unit 写简单名称
唯一且精确的 声明：function、声明：class 或 声明：unit
描述，必填；声明行之后的首个非空正文必须是描述
，可选；位于完整描述之后

标题层级和声明值必须符合下表，不允许在其他层级使用这些声明值：

位置	标题层级	允许的声明值
顶级声明	H2	`function`、`class`、`unit`
顶级 class 成员	H3	`function`、`class function`、`property`、`field`、`static field`、`const`、`static const`
unit interface direct member	H3	`function`、`var`、`const`、`class`
unit interface class 成员	H4	与顶级 class 成员相同

H2、H3、H4 中反引号包围的内容是 API 名称或调用签名。function、 class function、property 等声明术语只写在声明行中，不写进标题。

本标准中的“调用签名”只包含名称和参数名，例如 abs(x)，不是 TSL 声明语句 function abs(x);。声明行只参与文档结构识别，不属于名称、调用签名或调用语法。例如 class 下的 H3 标题 Save() 紧跟 声明：function，表示实例 function；可调用内容仍是 Save()，不能把两行拼成 function Save()。

每个 API 必须且只能写一行 声明：...，并将它作为标题后的第一条非空正文。 声明 后使用全角冒号，声明值使用本标准规定的小写形式。普通内容标题不包含反引号，也不紧跟声明行，因此不进入 API 索引；普通 H2 同时结束前一个顶级声明的正文范围。

同一所属范围和声明种类内，重复 class/unit 名称或重复 function 调用签名不允许； function 重载和跨声明种类同名允许。

function

页面结构

顶级 function 使用 H2，function 的示例标题使用 H3。每个 function 声明按以下顺序书写：

## \调用签名``
声明：function
函数描述，必填
，可选
参数表，有参数时必填
参数取值说明，可选
返回：类型
### 示例，可选；包含一个或多个“范例NN：说明”和独立的 tsl 代码块

参数表

参数表固定为三列：

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

规则：

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

参数取值

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

**mode 取值**

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

返回类型

每个顶层 function 必须包含非空返回类型：

返回：array

示例代码

每个示例以“范例NN：说明”开头，编号按出现顺序排列并至少保留两位
代码围栏使用 tsl
一个代码围栏只放一个独立示例
字符串使用直引号 ' 或 "
注释使用 //，不使用 (* *)
每条语句保留分号
没有输出时可以省略输出注释
单行输出写成 // 输出：<值>
多行输出第一行写 // 输出：，后续每一行输出都以 // 开头

多行输出示例：

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

完整页面示例

以下 API 仅用于说明存储格式，不代表真实 TSL API：

# 示例 / 数组

## `demoFn(src, mode, factor, ...)`

声明：function

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

<!-- tags: 示例 数组 -->

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

**mode 取值**

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

返回：array

### 示例

范例01：指定处理模式和系数

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

范例02：使用默认系数

```tsl
src := array(1, 1, 2);
return demoFn(src, 0);
```

## `demoNow()`

声明：function

返回示例值

返回：integer

class

页面结构

顶级 class 使用 H2，class 成员使用 H3，function 的参数取值或示例使用 H4。H2 正文按以下顺序书写：

## \ClassName``
声明：class
class 描述，必填
tags，可选；位于完整描述之后
父类：BaseClass，可选；多父类按声明顺序列出
class 成员，按声明顺序书写

成员标题与正文

class 成员标题统一只写反引号包围的名称或调用签名，例如 ### \Create(name)`、### `Title``。成员的声明种类由标题后的声明行表达：

实例方法：声明：function
类方法：声明：class function
property：声明：property
实例/静态字段：声明：field / 声明：static field
实例/静态常量：声明：const / 声明：static const

每个成员都按“标题、声明行、描述、tags、成员数据”的共同顺序开始。function 的正文结构与顶级 function 相同，实例 function 和 class function 都按描述、tags、参数表、参数取值、返回类型、示例的顺序书写。源码声明了返回类型时必须写 返回：类型；没有返回类型时省略，不补写 void。位于 class 中时，标题及其子标题整体下移一级：function 标题从 H2 变为 H3，参数取值和示例标题从 H3 变为 H4。成员另外必须写 可见性：public|protected，并可写 修饰符；类方法由 声明：class function 表达。

property 必须写访问方式；有类型时写 类型：...，没有类型时省略。field 必须写类型，const 必须写值。

完整页面示例

以下示例以 OpenXmlAttribute 的公开成员为基础，并加入一个 class function，用于说明 class 的 markdown 存储格式：

# OfficeXml / OpenXml

## `OpenXmlAttribute`

声明：class

表示一个 OpenXml 属性

<!-- tags: OpenXml XML 属性 -->

### `create(_prefix, _local_name)`

声明：function

创建不带初始值的 OpenXml 属性

<!-- tags: OpenXml 属性 创建 -->

可见性：`public`

修饰符：`overload`

| 参数          | 类型   | 说明         |
| ------------- | ------ | ------------ |
| `_prefix`     | string | 命名空间前缀 |
| `_local_name` | string | 本地名称     |

### `create(_prefix, _local_name, _value)`

声明：function

创建带初始值的 OpenXml 属性

<!-- tags: OpenXml 属性 创建 -->

可见性：`public`

修饰符：`overload`

| 参数          | 类型   | 说明         |
| ------------- | ------ | ------------ |
| `_prefix`     | string | 命名空间前缀 |
| `_local_name` | string | 本地名称     |
| `_value`      | any    | 属性值       |

### `CreateVirtual(position, row_index, _story)`

声明：class function

创建虚段落

可见性：`public`

| 参数        | 类型      | 说明     |
| ----------- | --------- | -------- |
| `position`  | integer   | 段落位置 |
| `row_index` | integer   | 行索引   |
| `_story`    | StoryNode | 故事节点 |

返回：ParagraphSegment

### `Prefix`

声明：property

命名空间前缀

可见性：`public`

类型：string

访问：read / write

### `LocalName`

声明：property

本地名称

可见性：`public`

类型：string

访问：read / write

### `ElementName`

声明：property

包含前缀的完整属性名称

可见性：`public`

类型：string

访问：read / write

### `Value`

声明：property

属性值

可见性：`public`

类型：any

访问：read / write

### `NamespaceUri`

声明：property

命名空间 URI

可见性：`public`

类型：string

访问：read / write

unit

页面结构

顶级 unit 使用 H2，interface direct member 使用 H3，interface class 的成员或 unit function 的参数取值/示例使用 H4，interface class function 的参数取值/示例使用 H5。H2 正文按以下顺序书写：

## \UnitName``
声明：unit
unit 描述，必填
tags，可选；位于完整描述之后
interface direct member，按声明顺序书写

成员标题与正文

H3 direct member 标题只写名称或调用签名。标题后的声明行只允许：

interface function：声明：function
variable：声明：var
constant：声明：const
interface class：声明：class

每个 direct member 都按“标题、声明行、描述、tags、成员数据”的共同顺序开始。 unit direct member 都来自 interface，visibility 固定为 public，正文不重复记录。 unit function 复用顶级 function 格式并要求返回类型，var 必须写类型，const 必须写值。interface class 的 H4 成员复用顶级 class 的成员格式，并显式写 可见性：public|protected。

完整页面示例

# 示例 / 文档运行时

## `DocumentUnit`

声明：unit

提供文档运行时接口

<!-- tags: 运行时 文档 -->

### `DefaultSize`

声明：const

默认缓冲区大小

值：`100`

### `CurrentDocument`

声明：var

当前文档

类型：Document

### `OpenDocument(path)`

声明：function

打开文档

| 参数   | 类型   | 说明     |
| ------ | ------ | -------- |
| `path` | string | 文档路径 |

返回：Document

### `Document`

声明：class

文档对象

父类：`BaseDocument`

#### `Save()`

声明：function

保存文档

可见性：`public`

返回：boolean

综合示例

同一叶子页可以按文档顺序混合三种顶级声明。以下 API 仅用于说明存储格式，不代表真实 TSL API：

# OfficeXml / OpenXml

## `OpenXmlAttribute`

声明：class

表示 OpenXml 属性

<!-- tags: OpenXml XML 属性 -->

### `create(_prefix, _local_name)`

声明：function

创建属性

<!-- tags: OpenXml 属性 创建 -->

可见性：`public`

| 参数          | 类型   | 说明         |
| ------------- | ------ | ------------ |
| `_prefix`     | string | 命名空间前缀 |
| `_local_name` | string | 本地名称     |

## `ParseOpenXml(xml)`

声明：function

解析 OpenXml 文本

<!-- tags: OpenXml XML 解析 -->

| 参数  | 类型   | 说明         |
| ----- | ------ | ------------ |
| `xml` | string | OpenXml 文本 |

返回：OpenXmlElement

### 示例

范例01：解析文本

```tsl
return ParseOpenXml('<root/>');
```

## `OpenXmlRuntime`

声明：unit

提供 OpenXml 运行时接口

<!-- tags: OpenXml 运行时 -->

### `OpenXmlElement`

声明：class

表示文档元素

<!-- tags: OpenXml XML 元素 -->

#### `Save()`

声明：function

保存元素

可见性：`public`

返回：boolean

tsf 源码文档格式

tsf 主要使用 function、unit 和 type 三种顶层组织方式。本标准按这三种方式分别定义源码文档格式。每个 tsf 源码文档对应一个对外顶级声明。

function

独立顶层 function 可以在源码中记录函数级文档。签名、参数类型、默认参数和返回类型由源码声明提供，描述、标签、参数说明、枚举值和示例由文档块提供。

一个 function tsf 文件只以第一个顶层 function 作为对外主函数；后续辅助函数不属于该文件的对外文档
顶层 procedure 不在本节规定的 function 文档格式范围内
module 和 path 是页面级录入字段，不属于单个函数的文档块

文档块位置

文档块必须是主函数 begin 之后的第一段非空内容，并且位于任何可执行语句、编译指令或其他注释之前

文档块由连续的 /// 行组成，并允许按照函数体缩进。/// 之前的空白以及其后的一个可选空格不属于文档内容。遇到第一行非 /// 内容时，文档块结束；函数体后续位置的注释是普通注释

TSL 解释器将 /// 作为普通的 // 行注释；本标准使用第三个 / 区分文档行与普通注释

文档块结构

文档块按以下顺序书写：

函数描述，一行或多行，必填
@tags: 标签1 标签2，可选，最多一行，标签使用空白分隔
参数组，按声明顺序书写；每组先写 @param: name 参数说明，再按需紧跟一个 @values: name
@returns: 类型，可选，最多一行
示例组，可选，可以重复；所有示例组必须位于文档块末尾

空的 /// 行可以在多行函数描述或示例中保留空行。指令名固定为小写；未知指令、重复的 @tags:/@returns:、同一参数重复的 @param:/@values:，以及不符合上述顺序的指令均不符合本标准。@example: 可以重复，@output: 在同一示例组内最多出现一次。

写法	必填	json 映射	规则
描述正文	是	`declarations[].desc`	第一条指令之前的所有正文，保留换行
`@tags: 标签1 标签2`	否	`declarations[].tags`	使用一个或多个空白字符分隔；忽略首尾空白；标签本身不得包含空白
`@param: name 参数说明`	有参时	`declarations[].params[].desc`	第一个词是参数名，其余内容是说明；说明不得为空
`@values: name`	否	`declarations[].params[].values`	值表规则见下；参数必须已经由 `@param:` 声明
`@returns: 类型`	否	`declarations[].returns`	类型不得为空；与声明返回类型同时存在时必须一致
`@example: 示例说明`	否	`declarations[].examples[].desc`	开始一个示例组；说明不得为空
示例代码	示例组内	`declarations[].examples[].code`	内容行额外缩进两个空格；至少包含一个非空代码行
`@output:`	否	`declarations[].examples[].output`	原始输出额外缩进两个空格；存在时不得为空

@param: 和 @values: 中的参数名与函数声明大小写无关地匹配；映射后的参数名保留函数声明中的拼写。

字段来源与映射

以下字段由主函数声明以及必要的文档指令确定：

tsf 声明内容	json 字段	映射规则
函数名	`declarations[].name`	保留声明名称
函数名和参数名	`declarations[].signature`	规范化为只含名称的调用形式，不复制类型或默认值
参数类型	`declarations[].params[].type`	保留声明中的类型
参数默认值	`declarations[].params[].optional`	存在默认值时为 `true`，默认表达式不另建 json 字段
返回类型	`declarations[].returns`	取自声明和 `@returns:`，按下述规则合并

完整录入数据必须包含每个参数的显式类型和非空说明，并通过函数声明或 @returns: 提供返回类型。可选参数的说明仍应写清默认值含义；optional: true 只表达该参数可以省略。

返回类型按以下规则合并：

只有函数声明时，使用声明中的拼写
只有 @returns: 时，去除首尾空白后使用指令中的拼写
两处同时存在时，使用相同的词法规则拆分类型，忽略 token 之间的空白，并按 TSL 标识符大小写无关的规则比较标识符 token；其他 token 必须一致。两处类型必须匹配，映射后使用声明中的拼写
两处都不存在时，不满足顶级 function 的 returns 必填要求

本标准只定义类型的词法一致性，不定义类型别名等语义等价关系。

枚举值表

枚举值表使用分组格式，每一项在 /// 标记后额外缩进两个空格：

/// @param: mode 处理模式，默认 0
/// @values: mode
///   0: 原样返回
///   1: 去重
///   "auto": 自动判断

规则：

枚举值使用 json 标量写法：数字直接写，字符串使用双引号，布尔值使用 true/false；nil 等符号值按字符串写成 "nil"
不接受数组、对象或 json null
值和说明以值后的第一个分隔冒号分开；说明不得为空
保留枚举项的声明顺序
同一参数最多有一个非空值表，不允许重复值；不同 json 类型的值不视为重复，例如数字 1 与字符串 "1" 是两个值
@values: 引用的参数必须存在
tsf 作者必须保证枚举值与参数类型在语义上兼容

示例组

每个示例组以非空的 @example: 示例说明 开始。其后的代码行必须在 /// 标记后额外缩进两个空格。可选的 @output: 结束代码部分，其后的缩进行记录原始输出；下一个 @example: 开始新的示例组。第一个示例组出现后，不得再写参数、返回类型等其他函数级指令。

映射到录入数据时，移除代码和输出的两个结构缩进，保留其余空白和换行。示例说明、代码和输出分别映射为 examples[].desc、examples[].code 和 examples[].output。desc 与 code 必填且非空；output 可选，但出现时必须包含至少一个非空行。示例顺序保持不变。

code 只记录示例源码，不得包含标准输出标记 // 输出：。output 只记录原始输出，不写 // 注释标记。映射到 markdown 时：

所有示例共用一个 ### 示例 标题
每项按顺序写为“范例01：说明”“范例02：说明”
每项使用一个独立的 tsl 代码块
没有 output 时，代码块只包含 code
单行 output 在代码末尾写为 // 输出：<值>
多行 output 先写 // 输出：，再为每个输出行添加 // 和一个空格；空输出行使用单独的 //

完整 tsf 示例

以下内容应保存为 Normalize.tsf：

function Normalize(mode: integer = 0): integer;
begin
    /// 按指定模式处理并返回模式值
    /// @tags: 示例 枚举
    /// @param: mode 处理模式，默认 0
    /// @values: mode
    ///   0: 原样返回
    ///   1: 去重
    ///   2: 排序
    /// @returns: integer
    /// @example: 使用默认模式
    ///   return Normalize();
    /// @output:
    ///   0
    /// @example: 指定模式
    ///   return Normalize(1);
    return mode;
end;

对应的顶级 function 录入对象为：

{
  "kind": "function",
  "name": "Normalize",
  "signature": "Normalize(mode)",
  "desc": "按指定模式处理并返回模式值",
  "tags": ["示例", "枚举"],
  "params": [
    {
      "name": "mode",
      "type": "integer",
      "optional": true,
      "desc": "处理模式，默认 0",
      "values": [
        {"value": 0, "desc": "原样返回"},
        {"value": 1, "desc": "去重"},
        {"value": 2, "desc": "排序"}
      ]
    }
  ],
  "returns": "integer",
  "examples": [
    {
      "desc": "使用默认模式",
      "code": "return Normalize();",
      "output": "0"
    },
    {
      "desc": "指定模式",
      "code": "return Normalize(1);"
    }
  ]
}

class

Counter.tsf

type Counter = class
/// 表示计数器
/// @tags: 示例 计数
public
    /// 创建计数器
    /// @param: initial_value 初始值
    function create(initial_value: integer);

    /// 计算两个整数之和
    /// @tags: 示例 加法
    /// @param: x 第一个整数
    /// @param: y 第二个整数
    /// @returns: integer
    class function Add(x: integer; y: integer): integer;
    begin
        return x + y;
    end;

    /// 增加当前值
    /// @param: step 增量
    /// @returns: integer
    /// @example: 增加计数
    ///   counter := new Counter(1);
    ///   return counter.Increase(2);
    /// @output:
    ///   3
    function Increase(step: integer): integer;

    /// 当前值
    /// @tags: 状态
    property Value read value_ write value_;

    /// 显示名称
    Label: string;

    /// 最小值
    const Minimum = 0;

protected
    /// 已创建的计数器数量
    static CreatedCount: integer;

    /// 最大值
    static const Maximum = 100;

private
    /// 内部值
    value_: integer;
end;

type CounterState = class
/// 表示内部状态
public
    /// 状态码
    Code: integer;
end;

function Counter.create(initial_value: integer);
begin
    value_ := initial_value;
end;

function Counter.Increase(step: integer): integer;
begin
    value_ := value_ + step;
    return value_;
end;

对应的 class 录入对象为：

{
  "kind": "class",
  "name": "Counter",
  "desc": "表示计数器",
  "tags": ["示例", "计数"],
  "members": [
    {
      "kind": "method",
      "name": "create",
      "visibility": "public",
      "binding": "instance",
      "signature": "create(initial_value)",
      "desc": "创建计数器",
      "params": [
        {
          "name": "initial_value",
          "type": "integer",
          "desc": "初始值"
        }
      ]
    },
    {
      "kind": "method",
      "name": "Add",
      "visibility": "public",
      "binding": "class",
      "signature": "Add(x, y)",
      "desc": "计算两个整数之和",
      "tags": ["示例", "加法"],
      "params": [
        {
          "name": "x",
          "type": "integer",
          "desc": "第一个整数"
        },
        {
          "name": "y",
          "type": "integer",
          "desc": "第二个整数"
        }
      ],
      "returns": "integer"
    },
    {
      "kind": "method",
      "name": "Increase",
      "visibility": "public",
      "binding": "instance",
      "signature": "Increase(step)",
      "desc": "增加当前值",
      "params": [
        {
          "name": "step",
          "type": "integer",
          "desc": "增量"
        }
      ],
      "returns": "integer",
      "examples": [
        {
          "desc": "增加计数",
          "code": "counter := new Counter(1);\nreturn counter.Increase(2);",
          "output": "3"
        }
      ]
    },
    {
      "kind": "property",
      "name": "Value",
      "visibility": "public",
      "desc": "当前值",
      "tags": ["状态"],
      "access": "readwrite"
    },
    {
      "kind": "field",
      "name": "Label",
      "visibility": "public",
      "desc": "显示名称",
      "type": "string"
    },
    {
      "kind": "constant",
      "name": "Minimum",
      "visibility": "public",
      "desc": "最小值",
      "value": "0"
    },
    {
      "kind": "field",
      "name": "CreatedCount",
      "visibility": "protected",
      "desc": "已创建的计数器数量",
      "type": "integer",
      "static": true
    },
    {
      "kind": "constant",
      "name": "Maximum",
      "visibility": "protected",
      "desc": "最大值",
      "value": "100",
      "static": true
    }
  ]
}

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 成员。

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` 对应 `base/example.md`
`declarations`	是	非空顶级声明列表；每项由 `kind` 判别并要求 `name`，数组顺序即 H2 顺序

function

顶级 function 对象字段：

字段	必填	说明
`kind`	是	固定为 `function`
`name`	是	function 简单名称；必须与 `signature` 中的名称一致
`signature`	是	只包含名称和参数名的调用签名
`desc`	是	函数描述，可包含多行
`tags`	否	检索关键词列表；推荐填写，有助于更准确地识别和检索函数
`params`	有参时	参数列表；无参函数省略
`returns`	是	返回类型
`examples`	否	示例列表；按顺序映射为独立的 TSL 代码块

参数字段：

字段	必填	说明
`name`	是	参数名，与签名一致
`type`	是	参数类型
`desc`	是	参数说明
`optional`	否	`true` 表示可选参数；markdown 参数说明以 `可选。` 开头
`values`	否	枚举值列表，对应参数取值说明

values 每项包含：

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

examples 每项包含：

字段	必填	说明
`desc`	是	示例场景说明；对应“范例NN：说明”
`code`	是	不含代码围栏和标准输出注释的 TSL 代码
`output`	否	原始输出；按单行或多行规则映射为 `//` 输出注释

class

class 对象字段：

字段	必填	说明
`kind`	是	固定为 `class`
`name`	是	class 简单名称
`desc`	是	class 描述
`tags`	否	检索关键词列表
`bases`	否	按声明顺序保存的直接父类列表
`members`	是	method/property/field/constant 的有序列表

所有 class member 都要求 name、desc 和 visibility。所有 class member 都可以包含可选的 tags。visibility 只能是 public 或 protected。成员判别字段如下：

kind	关键字段
`method`	`signature`、`binding: instance\|class`；可选 `params/returns/modifiers/examples`
`property`	`access: read\|write\|readwrite`；可选 `type`，参数化时包含 `params`
`field`	`type`；可选 `static: true`
`constant`	`value`；可选 `type`、`static: true`

kind: method 对象不使用 static 字段；class function 由 binding: class 唯一表达。value 的存在性与真假值分开判断，因此数字 0 和布尔值 false 都是合法常量值。这里的 method 是录入结构内部用于统一表达实例 function 和 class function 的 kind，不对应 markdown 标题或 声明：... 行中的声明值。

unit

顶级 unit 对象包含固定的 kind: unit，以及必填的 name、desc、members 和可选 tags。direct member 按 interface 源码顺序保存，kind 只允许：

kind	关键字段
`function`	复用顶层 function 数据；`returns` 必填
`variable`	`name`、`desc`、`type`，可选 `tags`
`constant`	`name`、`desc`、`value`，可选 `tags/type`
`class`	复用完整 class 数据，并以 `kind: class` 作为成员判别字段

录入数据不保存 unit 的 uses、implementation、initialization 或 finalization。

录入文件格式

yaml

yaml 录入文件应符合以下规则：

examples[].code 和多行 examples[].output 使用 | 块标量
参数名 ... 必须加引号
nil|array 可直接作为普通字符串值

完整例子：examples/example.yaml

json

json 录入文件应符合以下规则：

json 不支持注释
多行 examples[].code 和 examples[].output 使用 \n
字符串内部的双引号使用 \"
结构标点必须使用半角字符

完整例子：examples/example.json

统一 API 索引

function_index.tsv 固定为 13 列：

name scope module signature page anchor tags summary kind binding visibility owner qualified_name

字段含义：

kind：function|class|method|property|field|constant|unit|variable
binding：不适用时为空，否则为 instance|class|static|unit
visibility：class member 为 public|protected，unit direct member 为 public
owner：不含该 API 名称的完整所属路径
qualified_name：点分隔的稳定文档身份

索引的 kind 和 binding 由声明行和所属层级按下表确定：

markdown 位置	`声明：...`	录入对象表达	索引 `kind`	索引 `binding`
H2 顶级声明	`function`	`kind: function`	`function`	空
H2 顶级声明	`class`	`kind: class`	`class`	空
H2 顶级声明	`unit`	`kind: unit`	`unit`	空
顶级/interface class 成员	`function`	`kind: method, binding: instance`	`method`	`instance`
顶级/interface class 成员	`class function`	`kind: method, binding: class`	`method`	`class`
顶级/interface class 成员	`property`	`kind: property`	`property`	`instance`
顶级/interface class 成员	`field`	`kind: field`	`field`	`instance`
顶级/interface class 成员	`static field`	`kind: field, static: true`	`field`	`static`
顶级/interface class 成员	`const`	`kind: constant`	`constant`	`instance`
顶级/interface class 成员	`static const`	`kind: constant, static: true`	`constant`	`static`
unit interface direct member	`function`	`kind: function`	`function`	`unit`
unit interface direct member	`var`	`kind: variable`	`variable`	`unit`
unit interface direct member	`const`	`kind: constant`	`constant`	`unit`
unit interface direct member	`class`	`kind: class`	`class`	`unit`

表中的 interface class 成员指 unit interface class 的 H4 成员；其允许的声明值和派生规则与顶级 class 的 H3 成员完全相同。

例如 class function Widget.Create 的 owner 是 Widget；unit interface class function DemoUnit.Document.Save 的 owner 是 DemoUnit.Document。重载共享 qualified_name，由 signature 和唯一的 page#anchor 区分。

37 KiB Raw Blame History Unescape Escape

TSL API 文档标准

目录

基本原则

markdown 存储格式

页面与统一顶级声明

function

页面结构

标签

参数表

参数取值

返回类型

示例代码

完整页面示例

class

页面结构

成员标题与正文

完整页面示例

unit

页面结构

成员标题与正文

完整页面示例

综合示例

tsf 源码文档格式

function

文档块位置

文档块结构

字段来源与映射

枚举值表

示例组

完整 tsf 示例

class

unit

录入数据结构

function

class

unit

录入文件格式

yaml

json

统一 API 索引

37 KiB

Raw Blame History