[YQL-14697] Add signatures, improve descriptions

ref:adce3420864dd7f3dfd157eb486950c41dd6767c

1 files changed, 222 insertions, 3 deletions

diff --git a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/types.md b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/types.md
index cf557a8e196..360ca4f5a25 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/types.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/builtins/_includes/types.md
@@ -1,11 +1,29 @@
 # Функции для работы с типами данных
 
+Помимо обычных функций, которые работают с конкретными значениями (типа FIND, COALESCE), YQL поддерживает функции для работами с [типами](../../types/index.md).
+Функции позволяют узнать тип произвольного выражения, проанализировать контейнерный тип и создавть новый контейнерный тип на основе имеющегося.
+
+**Примеры**
+``` yql
+$itemType = TypeOf($item);
+SELECT CAST($foo AS ListType($itemType));  -- каст $foo к типу List<$itemType> 
+```
+
 ## FormatType {#formattype}
 
+**Сигнатура**
+```
+FormatType(Type)->String
+```
+
 Сериализация типа {% if feature_codegen %} или хендла типа{% endif %} в человекочитаемую строку. Это полезно для отладки, а также будет использоваться в последующих примерах данного раздела. [Документация по формату](../../types/type_string.md).
 
 ## ParseType {#parsetype}
 
+**Сигнатура**
+```
+ParseType(String)->Type
+```
 Построение типа по строке с его описанием. [Документация по её формату](../../types/type_string.md).
 
 **Примеры**
@@ -15,6 +33,10 @@ SELECT FormatType(ParseType("List<Int32>"));  -- List<int32>
 
 ## TypeOf {#typeof}
 
+**Сигнатура**
+```
+TypeOf(<any expression>)->Type
+```
 Получение типа значения, переданного в аргумент.
 
 **Примеры**
@@ -27,21 +49,32 @@ SELECT FormatType(TypeOf(AsTuple(1, 1u))); -- Tuple<Int32,Uint32>
 
 ## InstanceOf {#instanceof}
 
-Возвращает экземпляр указанного типа, который можно использовать только для получения типа результата выражения с его использованием.
+**Сигнатура**
+```
+InstanceOf(Type)->объект типа Type
+```
 
-Если этот экземпляр останется в графе вычислений к моменту окончания оптимизации, то операция будет завершена с ошибкой.
+Возвращает экземпляр объекта указанного типа. Полученный объект не имеет какого-то определенного значения.
+InstanceOf можно использовать только в том случае, если результат выражения в котором InstanceOf используется зависит от типа InstanceOf, но не от значения.   
+В противном случае операция будет завершена с ошибкой.
 
 **Примеры**
 ``` yql
+SELECT InstanceOf(ParseType("Int32")) + 1.0; -- ошибка (Can't execute InstanceOf): результат зависит от (неопределенного) значения InstanceOf
 SELECT FormatType(TypeOf(
     InstanceOf(ParseType("Int32")) +
     InstanceOf(ParseType("Double"))
-)); -- Double, так как "Int32 + Double" возвращает Double
+)); -- вернет Double, так как сложение Int32 и Double возвращает Double (InstanceOf используется в контексте, где важен только его тип, но не значение) 
 ```
 
 ## DataType {#datatype}
 
+**Сигнатура**
+```
+DataType(String, [String, ...])->Type
+```
 Возвращает тип для [примитивных типов данных](../../types/primitive.md) по его имени.
+Для некоторых типов (например Decimal) необходимо передавать параметры типа в качестве дополнительных аргументов.
 
 **Примеры**
 ``` yql
@@ -51,15 +84,26 @@ SELECT FormatType(DataType("Decimal","5","1")); -- Decimal(5,1)
 
 ## OptionalType {#optionaltype}
 
+**Сигнатура**
+```
+OptionalType(Type)->опциональный Type
+```
 Добавляет в переданный тип возможность содержать `NULL`.
 
 **Примеры**
 ``` yql
 SELECT FormatType(OptionalType(DataType("Bool"))); -- Bool?
+SELECT FormatType(OptionalType(ParseType("List<String?>"))); -- List<String?>?
 ```
 
 ## ListType и StreamType {#listtype}
 
+**Сигнатура**
+```
+ListType(Type)->тип списка с элементами типа Type
+StreamType(Type)->тип потока с элементами типа Type
+```
+
 Строит тип списка или потока по переданному типу элемента.
 
 **Примеры**
@@ -69,6 +113,11 @@ SELECT FormatType(ListType(DataType("Bool"))); -- List<Bool>
 
 ## DictType {#dicttype}
 
+**Сигнатура**
+```
+DictType(Type, Type)->тип словаря
+```
+
 Строит тип словаря по переданным типам ключа (первый аргумент) и значения (второй аргумент).
 
 **Примеры**
@@ -81,6 +130,10 @@ SELECT FormatType(DictType(
 
 ## TupleType {#tupletype}
 
+**Сигнатура**
+```
+TupleType(Type, ...)->тип кортежа
+```
 Строит тип кортежа по переданным типам элементов.
 
 **Примеры**
@@ -94,6 +147,10 @@ SELECT FormatType(TupleType(
 
 ## StructType {#structtype}
 
+**Сигнатура**
+```
+StructType(Type AS ElementName1, Type AS ElementName2, ...)->тип структуры
+```
 Строит тип структуры по переданным типам элементов. Для указания имен элементов используется стандартный синтаксис именованных аргументов.
 
 **Примеры**
@@ -106,6 +163,11 @@ SELECT FormatType(StructType(
 
 ## VariantType {#varianttype}
 
+**Сигнатура**
+```
+VariantType(StructType)->тип варианта над структурой
+VariantType(TupleType)->тип варианта над кортежем
+```
 Возвращает тип варианта по низлежащему типу (структуры или кортежа).
 
 **Примеры**
@@ -117,6 +179,10 @@ SELECT FormatType(VariantType(
 
 ## ResourceType {#resourcetype}
 
+**Сигнатура**
+```
+ResourceType(String)->тип ресурса
+```
 Возвращает тип [ресурса](../../types/special.md) по переданной строковой метке.
 
 **Примеры**
@@ -126,6 +192,10 @@ SELECT FormatType(ResourceType("Foo")); -- Resource<'Foo'>
 
 ## CallableType {#callabletype}
 
+**Сигнатура**
+```
+CallableType(Uint32, Type, [Type, ...])->тип вызываемого значения
+```
 Строит тип вызываемого значения по следующим аргументам:
 
 1. Число опциональных аргументов (если все обязательные — 0).
@@ -144,6 +214,12 @@ SELECT FormatType(CallableType(
 
 ## GenericType, UnitType и VoidType {#generictype}
 
+**Сигнатура**
+```
+GenericType()->тип
+UnitType()->тип
+VoidType()->тип
+```
 Возвращают одноименные [специальные типы данных](../../types/special.md). Аргументов нет, так как они не параметризуются.
 
 **Примеры**
@@ -153,6 +229,13 @@ SELECT FormatType(VoidType()); -- Void
 
 ## OptionalItemType, ListItemType и StreamItemType {#optionalitemtype}
 
+**Сигнатура**
+```
+OptionalItemType(OptionalType)->тип элемента опционального типа
+ListItemType(ListType)->тип элемента списочного типа
+StreamItemType(StreamType)->тип элемента потокового типа
+```
+
 {% if feature_codegen %} Если этим функциям передается тип, то они выполняют{% else %}Выполняют{% endif %} действие, обратное [OptionalType](#optionaltype), [ListType](#listtype) и [StreamType](#streamtype) — возвращают тип элемента по типу соответствующего контейнера.
 {% if feature_codegen %}
 Если этим функциям передается хендл типа, то выполняют действие, обратное [OptionalTypeHandle](#optionaltypehandle), [ListTypeHandle](#listtypehandle) и [StreamTypeHandle](#streamtypehandle) - возвращают хендл типа элемента по хендлу типа соответствующего контейнера.
@@ -174,6 +257,11 @@ SELECT FormatType(ListItemType(
 
 ## DictKeyType и DictPayloadType {#dictkeytype}
 
+**Сигнатура**
+```
+DictKetType(DictType)->тип ключа словаря
+DictPayloadType(DictType)->тип значения словаря
+```
 Возвращают тип ключа или значения по типу словаря.
 
 **Примеры**
@@ -185,6 +273,10 @@ SELECT FormatType(DictKeyType(
 
 ## TupleElementType {#tupleelementtype}
 
+**Сигнатура**
+```
+TupleElementType(TupleType, String)->тип элемента кортежа
+```
 Возвращает тип элемента кортежа по типу кортежа и индексу элемента (индекс с нуля).
 
 **Примеры**
@@ -196,6 +288,10 @@ SELECT FormatType(TupleElementType(
 
 ## StructMemberType {#structmembertype}
 
+**Сигнатура**
+```
+StructMemberType(StructType, String)->тип элемента структуры
+```
 Возвращает тип элемента структуры по типу структуры и имени элемента.
 
 **Примеры**
@@ -207,6 +303,11 @@ SELECT FormatType(StructMemberType(
 
 ## CallableResultType и CallableArgumentType {#callableresulttype}
 
+**Сигнатура**
+```
+CallableResultType(CallableType)->тип результата вызываемого значения
+CallableArgumentType(CallableType, Uint32)->тип аругмента вызываемого значения
+```
 `CallableResultType` возвращает тип результата по типу вызываемого значения, а `CallableArgumentType` — тип аргумента по типу вызываемого значения и его индексу (индекс с нуля).
 
 **Примеры**
@@ -223,6 +324,10 @@ FormatType(CallableArgumentType(
 
 ## VariantUnderlyingType {#variantunderlyingtype}
 
+**Сигнатура**
+```
+VariantUnderlyingType(VariantType)->низлежащий тип варианта
+```
 {% if feature_codegen %}Если этой функции передается тип, то она выполняет{% else %}Выполняет{% endif %} действие, обратное [VariantType](#varianttype) — возвращает низлежащий тип по типу варианта.
 {% if feature_codegen %}
 Если этой функции передается хендл типа, то она выполняет действие, обратное [VariantTypeHandle](#varianttypehandle) — возвращает хендл низлежащего типа по хендлу типа варианта.
@@ -257,12 +362,21 @@ FormatType(VariantUnderlyingType(
 
 Получение хендла типа из типа, переданного в аргумент.
 
+**Сигнатура**
+```
+TypeHandle(Type)->хэндл типа
+```
+
 **Примеры:**
 ``` yql
 SELECT FormatType(TypeHandle(TypeOf("foo")));  -- String
 ```
 ## EvaluateType
 
+**Сигнатура**
+```
+EvaluateType(TypeHandle)->тип
+```
 Получение типа из хендла типа, переданного в аргумент. Функция вычисляется до начала основного расчета, как и [EvaluateExpr](../basic.md#evaluate_expr_atom).
 
 **Примеры:**
@@ -272,6 +386,10 @@ SELECT FormatType(EvaluateType(TypeHandle(TypeOf("foo"))));  -- String
 
 ## ParseTypeHandle
 
+**Сигнатура**
+```
+ParseTypeHandle(String)->хэндл типа
+```
 Построение хендла типа по строке с его описанием. [Документация по её формату](../../types/type_string.md).
 
 **Примеры:**
@@ -281,6 +399,10 @@ SELECT FormatType(ParseTypeHandle("List<Int32>"));  -- List<int32>
 
 ## TypeKind
 
+**Сигнатура**
+```
+TypeKind(TypeHandle)->String
+```
 Получение названия верхнего уровня типа из хендла типа, переданного в аргумент.
 
 **Примеры:**
@@ -291,6 +413,10 @@ SELECT TypeKind(ParseTypeHandle("List<Int32>"));  -- List
 
 ## DataTypeComponents
 
+**Сигнатура**
+```
+DataTypeComponents(DataTypeHandle)->List<String>
+```
 Получение названия и параметров [примитивного типа данных](../../types/primitive.md) из хендла примитивного типа, переданного в аргумент. Обратная функция - [DataTypeHandle](#datatypehandle).
 
 **Примеры:**
@@ -301,6 +427,10 @@ SELECT DataTypeComponents(ParseTypeHandle("Decimal(4,1)"));  -- ["Decimal", "4",
 
 ## DataTypeHandle
 
+**Сигнатура**
+```
+DataTypeHandle(List<String>)->хэндл примитивного типа данных
+```
 Построение хендла [примитивного типа данных](../../types/primitive.md) из его названия и параметров, переданных списком в аргумент. Обратная функция - [DataTypeComponents](#datatypecomponents).
 
 **Примеры:**
@@ -316,6 +446,10 @@ SELECT FormatType(DataTypeHandle(
 
 ## OptionalTypeHandle
 
+**Сигнатура**
+```
+OptionalTypeHandle(TypeHandle)->хэндл опционального типа
+```
 Добавляет в переданный хендл типа возможность содержать `NULL`.
 
 **Примеры:**
@@ -327,6 +461,11 @@ SELECT FormatType(OptionalTypeHandle(
 
 ## ListTypeHandle и StreamTypeHandle {#list-stream-typehandle}
 
+**Сигнатура**
+```
+ListTypeHandle(TypeHandle)->хэндл списочного типа
+StreamTypeHandle(TypeHandle)->хэндл потокового типа
+```
 Строит хендл типа списка или потока по переданному хендлу типа элемента.
 
 **Примеры:**
@@ -338,6 +477,11 @@ SELECT FormatType(ListTypeHandle(
 
 ## EmptyListTypeHandle и EmptyDictTypeHandle
 
+**Сигнатура**
+```
+EmptyListTypeHandle()->хэндл типа пустого списка
+EmptyDictTypeHandle()->хэндл типа пустого словаря
+```
 Строит хендл типа пустого списка или словаря.
 
 **Примеры:**
@@ -347,6 +491,10 @@ SELECT FormatType(EmptyListTypeHandle()); -- EmptyList
 
 ## TupleTypeComponents
 
+**Сигнатура**
+```
+TupleTypeComponents(TupleTypeHandle)->List<TypeHandle>
+```
 Получение списка хендлов типов элементов из хендла типа кортежа, переданного в аргумент. Обратная функция - [TupleTypeHandle](#tupletypehandle).
 
 **Примеры:**
@@ -363,6 +511,10 @@ SELECT ListMap(
 
 ## TupleTypeHandle
 
+**Сигнатура**
+```
+TupleTypeHandle(List<TypeHandle>)->хэндл типа кортежа
+```
 Построение хендла типа кортежа из хендлов типов элементов, переданных списком в аргумент. Обратная функция - [TupleTypeComponents](#tupletypecomponents).
 
 **Примеры:**
@@ -379,6 +531,10 @@ SELECT FormatType(
 
 ## StructTypeComponents
 
+**Сигнатура**
+```
+StructTypeComponents(StructTypeHandle)->List<Struct<Name:String, Type:TypeHandle>>
+```
 Получение списка хендлов типов элементов и их имен из хендла типа структуры, переданного в аргумент. Обратная функция - [StructTypeHandle](#structtypehandle).
 
 **Примеры:**
@@ -398,6 +554,10 @@ SELECT ListMap(
 
 ## StructTypeHandle
 
+**Сигнатура**
+```
+StructTypeHandle(List<Struct<Name:String, Type:TypeHandle>>)->хэндл типа структуры
+```
 Построение хендла типа структуры из хендлов типов элементов и имен, переданных списком в аргумент. Обратная функция - [StructTypeComponents](#structtypecomponents).
 
 **Примеры:**
@@ -414,6 +574,10 @@ SELECT FormatType(
 
 ## DictTypeComponents
 
+**Сигнатура**
+```
+DictTypeComponents(DictTypeHandle)->Struct<Key:TypeHandle, Payload:TypeHandle>
+```
 Получение хендла типа-ключа и хендла типа-значения - из хендла типа словаря, переданного в аргумент. Обратная функция - [DictTypeHandle](#dicttypehandle).
 
 **Примеры:**
@@ -427,6 +591,10 @@ SELECT
 
 ## DictTypeHandle
 
+**Сигнатура**
+```
+DictTypeHandle(TypeHandle, TypeHandle)->хэндл типа словаря
+```
 Построение хендла типа словаря из хендла типа-ключа и хендла типа-значения, переданных в аргументы. Обратная функция - [DictTypeComponents](#dicttypecomponents).
 
 **Примеры:**
@@ -441,6 +609,10 @@ SELECT FormatType(
 
 ## ResourceTypeTag
 
+**Сигнатура**
+```
+ResourceTypeTag(ResourceTypeHandle)->String
+```
 Получение тега из хендла типа ресурса, переданного в аргумент. Обратная функция - [ResourceTypeHandle](#resourcetypehandle).
 
 **Примеры:**
@@ -450,6 +622,10 @@ SELECT ResourceTypeTag(ParseTypeHandle("Resource<foo>")); -- foo
 
 ## ResourceTypeHandle
 
+**Сигнатура**
+```
+ResourceTypeHandle(String)->хэндл типа ресурса  
+```
 Построение хендла типа ресурса по значению тега, переданного в аргумент. Обратная функция - [ResourceTypeTag](#resourcetypetag).
 
 **Примеры:**
@@ -459,6 +635,10 @@ SELECT FormatType(ResourceTypeHandle("foo")); -- Resource<'foo'>
 
 ## TaggedTypeComponents
 
+**Сигнатура**
+```
+TaggedTypeComponents(TaggedTypeHandle)->Struct<Base:TypeHandle, Tag:String>
+```
 Получение тега и базового типа из хендла декорированного типа, переданного в аргумент. Обратная функция - [TaggedTypeHandle](#taggedtypehandle).
 
 **Примеры:**
@@ -470,6 +650,10 @@ SELECT FormatType($t.Base), $t.Tag; -- Int32, foo
 
 ## TaggedTypeHandle
 
+**Сигнатура**
+```
+TaggedTypeHandle(TypeHandle, String)->хэндл декорированного типа  
+```
 Построение хендла декорированного типа по хендлу базового типа и имени тега, переданных в аргументах. Обратная функция - [TaggedTypeComponents](#taggedtypecomponents).
 
 **Примеры:**
@@ -481,6 +665,11 @@ SELECT FormatType(TaggedTypeHandle(
 
 ## VariantTypeHandle
 
+**Сигнатура**
+```
+VariantTypeHandle(StructTypeHandle)->хэндл типа варианта над структурой
+VariantTypeHandle(TupleTypeHandle)->хэндл типа варианта над кортежем
+```
 Построение хендла типа варианта по хендлу низлежащего типа, переданного в аргумент. Обратная функция - [VariantUnderlyingType](#variantunderlyingtype).
 
 **Примеры:**
@@ -492,6 +681,11 @@ SELECT FormatType(VariantTypeHandle(
 
 ## VoidTypeHandle и NullTypeHandle
 
+**Сигнатура**
+```
+VoidTypeHandle()->хэндл типа Void
+NullTypeHandle()->хэндл типа Null
+```
 Построение хендла типов Void и Null соответственно.
 
 **Примеры:**
@@ -502,6 +696,19 @@ SELECT FormatType(NullTypeHandle()); -- Null
 
 ## CallableTypeComponents
 
+**Сигнатура**
+```
+CallableTypeComponents(CallableTypeHandle)->
+Struct<
+    Arguments:List<Struct<
+        Flags:List<String>,
+        Name:String,
+        Type:TypeHandle>>,
+    OptionalArgumentsCount:Uint32,
+    Payload:String,
+    Result:TypeHandle
+>
+```
 Получение описания хендла типа вызываемого значения, переданного в аргумент. Обратная функция - [CallableTypeHandle](#callabletypehandle).
 
 **Примеры:**
@@ -535,6 +742,10 @@ SELECT $formatCallable(
 
 ## CallableArgument
 
+**Сигнатура**
+```
+CallableArgument(TypeHandle, [String, [List<String>]])->Struct<Flags:List<String>,Name:String,Type:TypeHandle>
+```
 Упаковка в структуру описания аргумента вызываемого значения для передачи в функцию [CallableTypeHandle](#callabletypehandle) по следующим аргументам:
 
 1. Хендл типа аргумента.
@@ -543,6 +754,10 @@ SELECT $formatCallable(
 
 ## CallableTypeHandle
 
+**Сигнатура**
+```
+CallableTypeHandle(TypeHandle, List<Struct<Flags:List<String>,Name:String,Type:TypeHandle>>, [Uint32, [String]])->хэндл типа вызываемого значения 
+```
 Построение хендла типа вызываемого значения по следующим аргументам:
 
 1. Хендл типа возвращаемого значения.
@@ -568,6 +783,10 @@ SELECT FormatType(
 
 ## LambdaArgumentsCount
 
+**Сигнатура**
+```
+LambdaArgumentsCount(LambdaFunction)->Uint32 
+```
 Получение количества аргументов в лямбда-функции.
 
 **Примеры:**