📝 docs(tsl): align syntax annotations and examples

2026-01-11 12:53:30 +08:00
parent 37546fe4f7
commit e3ecd26a88
5 changed files with 219 additions and 135 deletions
@@ -144,6 +144,7 @@
        - [多维数组的理解](#多维数组的理解)
        - [字符串也可以作为数组的下标](#字符串也可以作为数组的下标)
        - [数组的表达方式](#数组的表达方式)
+        - [Array of 类型注解（可选）](#array-of-类型注解可选)
        - [TSL 语言的数组和其他语言相比的特性](#tsl-语言的数组和其他语言相比的特性)
      - [TMatrix](#tmatrix)
      - [Matrix](#matrix)
@@ -157,6 +158,7 @@
        - [COM 方法的调用例子](#com-方法的调用例子)
      - [TSLObj](#tslobj)
    - [常量与变量](#常量与变量)
+      - [类型注解](#类型注解)
      - [全局变量](#全局变量)
      - [常量](#常量)
        - [常量及常量成员的定义与初始化](#常量及常量成员的定义与初始化)
@@ -1831,6 +1833,17 @@ d := array(1 + 3, 2 + 5);
 empty := array();
 ```

+##### Array of 类型注解（可选）
+
+类型注解可用 `array of <label>` 标注元素含义，支持嵌套（如 `array of array of real`）。注解仅用于说明，编译器不做类型检查。
+
+```tsl
+function Clone(items: array of string): array of string;
+begin
+    return items;
+end;
+```
+
 ##### TSL 语言的数组和其他语言相比的特性

 - 支持字符串下标，便于按名称访问。
@@ -2034,6 +2047,19 @@ today := Date();

 变量 dToday 通过 Date()函数的返回，被赋值为一个 TDateTime 类型的数据。

+#### 类型注解
+
+类型注解使用 `:` 指定标识符类型，常见于函数参数/返回值、类字段和属性声明。
+
+注解名称不参与编译检查，可任意命名，仅用于说明与阅读。
+
+```tsl
+function Open(path: string; flags: options = 0): result;
+begin
+    return array("path": path, "flags": flags);
+end;
+```
+
 常量即同 C 语言中的常量，它是一个固定值，在程序执行期间不会改变。

 截止到 2023-07 月份前的 TSL 版中，TSL 中没有特定的常量标识符，即不支持通过 const 来定义一个常量标识符。
@@ -8,6 +8,7 @@
  - [目录](#目录)
  - [函数定义体和函数](#函数定义体和函数)
    - [概念](#概念)
+    - [参数类型与返回类型](#参数类型与返回类型)
    - [主函数与子函数](#主函数与子函数)
    - [形式参数与实际参数](#形式参数与实际参数)
      - [值参数](#值参数)
@@ -71,6 +72,29 @@ TSL 仅允许 `return` 一个值，如果需要返回多个内容，建议用数
 ```tsl
 return array(x, y);
 ```
+
+### 参数类型与返回类型
+
+函数参数与返回值可以在名称后使用 `:` 指定类型，类型注解可选。注解名称不参与编译检查，可任意命名，仅用于说明与阅读。
+
+参数分隔规则：
+
+- 不带类型注解时，用逗号分隔参数，例如 `function f1(a, b);`
+- 带类型注解时，用分号分隔参数，例如 `function f2(a: string; b: array of real);`
+- 返回值类型在 `)` 之后定义，例如 `function f3(): void;`
+
+```tsl
+function SafeConvert(value: input_value; convert_func: handler): real;
+begin
+    return ##convert_func(value);
+end;
+
+function Open(path: string; flags: options = 0): result;
+begin
+    return array("path": path, "flags": flags);
+end;
+```
+
 ### 主函数与子函数

 在 TSL 语言中，根据函数的可使用范围，将函数分成主函数和子函数两种。
@@ -16,6 +16,7 @@
    - [作用域](#作用域)
  - [字段](#字段)
    - [字段简介](#字段简介)
+    - [字段类型与弱引用](#字段类型与弱引用)
    - [static 静态字段](#static-静态字段)
    - [const 常量成员](#const-常量成员)
  - [方法](#方法)
@@ -529,6 +530,19 @@ myObj.Field1 := "This is a Field";

 可以为字段指定作用域

+#### 字段类型与弱引用
+
+字段可以使用 `:` 指定类型。类型注解不参与编译检查，可任意命名，仅用于说明与阅读。对于对象字段，可用 `[weakref]` 标记为弱引用，用于避免循环引用。
+
+```tsl
+type Node = class
+protected
+    [weakref]parent_: Node;
+    children_: array of Node;
+    meta_: meta_info;
+end;
+```
+
 #### static 静态字段

 在字段的前边加入 static 前缀，就表明为静态字段也称静态成员变量，静态字段就是全部类实例共用的字段，亦可以不用实例化来进行调用。
@@ -1279,6 +1293,12 @@ class(ClassName).FuncName();

 语法：`Property PropertyName[(ParamList)] [read fieldOrMethod][write fieldOrMethod][Index IndexValue]`

+属性名后可指定类型，语法：`property Name: Type read fieldOrMethod [write fieldOrMethod]`。类型注解不参与编译检查，可任意命名。
+
+```tsl
+property Components: DocxComponentsFacade read components_;
+```
+
 其中，

 1、关键字 Property 关键字表示开始声明了一个属性；