# TSL API 文档标准

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

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

## 目录

- [TSL API 文档标准](#tsl-api-文档标准)
  - [目录](#目录)
  - [基本原则](#基本原则)
  - [markdown 存储格式](#markdown-存储格式)
    - [页面与统一顶级声明](#页面与统一顶级声明)
    - [function](#function)
    - [class](#class)
    - [unit](#unit)
    - [综合示例](#综合示例)
  - [tsf 源码文档格式](#tsf-源码文档格式)
    - [function](#function-1)
    - [class](#class-1)
    - [unit](#unit-1)
  - [录入数据结构](#录入数据结构)
    - [function](#function-2)
    - [class](#class-2)
    - [unit](#unit-2)
  - [录入文件格式](#录入文件格式)
    - [yaml](#yaml)
    - [json](#json)
  - [统一 API 索引](#统一-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 叶子页可以收录多个对外顶级声明。

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

1. H2 标题：function 写调用签名，class 和 unit 写简单名称
2. 唯一且精确的 `声明：function`、`声明：class` 或 `声明：unit`
3. 描述，必填；声明行之后的首个非空正文必须是描述
4. `<!-- tags: 关键词1 关键词2 -->`，可选；位于完整描述之后

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

| 位置                         | 标题层级 | 允许的声明值                                                                               |
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| 顶级声明                     | 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 声明按以下
顺序书写：

1. `## \`调用签名\``
2. `声明：function`
3. 函数描述，必填
4. `<!-- tags: 关键词1 关键词2 -->`，可选
5. 参数表，有参数时必填
6. 参数取值说明，可选
7. `返回：类型`
8. `### 示例`，可选；包含一个或多个“范例NN：说明”和独立的 `tsl` 代码块

#### 标签

标签位于完整函数描述之后，用空格分隔检索关键词：

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

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

#### 参数表

参数表固定为三列：

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

规则：

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

#### 参数取值

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

```markdown
**mode 取值**

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

#### 返回类型

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

```markdown
返回：array
```

#### 示例代码

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

多行输出示例：

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

#### 完整页面示例

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

````markdown
# 示例 / 数组

## `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 正文
按以下顺序书写：

1. `## \`ClassName\``
2. `声明：class`
3. class 描述，必填
4. tags，可选；位于完整描述之后
5. `父类：BaseClass`，可选；多父类按声明顺序列出
6. 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 存储格式：

```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 正文按以下顺序书写：

1. `## \`UnitName\``
2. `声明：unit`
3. unit 描述，必填
4. tags，可选；位于完整描述之后
5. 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`。

#### 完整页面示例

```markdown
# 示例 / 文档运行时

## `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：

````markdown
# 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 解释器将 `///` 作为普通的 `//` 行注释；本标准使用第三个 `/` 区分文档行与普通
注释

#### 文档块结构

文档块按以下顺序书写：

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

空的 `///` 行可以在多行函数描述或示例中保留空行。指令名固定为小写；未知指令、
重复的 `@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` 必填要求

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

#### 枚举值表

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

```text
/// @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`：

```tsl
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 录入对象为：

```json
{
  "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`

```tsl
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 录入对象为：

```json
{
  "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](examples/example.yaml)

### json

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

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

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

## 统一 API 索引

`function_index.tsv` 固定为 13 列：

```text
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` 区分。