From 3f69d85f736f5638dddf97b5c01dc11aca2ac5c0 Mon Sep 17 00:00:00 2001
From: Philipp Ossler <philipp.ossler@gmail.com>
Date: Fri, 30 Aug 2024 09:45:07 +0200
Subject: [PATCH 1/5] feat(feel): Clarify built-in function usage

Extend the description of the functions `date()`, `number()`, and `substring()` to clarify the behavior for certain edge cases.
---
 .../feel-built-in-functions-conversion.md            | 11 +++++++++++
 .../feel-built-in-functions-string.md                | 12 +++++++++++-
 .../feel/language-guide/feel-temporal-expressions.md |  3 +++
 .../feel-built-in-functions-conversion.md            | 11 +++++++++++
 .../feel-built-in-functions-string.md                | 12 +++++++++++-
 .../feel/language-guide/feel-temporal-expressions.md |  3 +++
 .../feel-built-in-functions-conversion.md            | 11 +++++++++++
 .../feel-built-in-functions-string.md                | 12 +++++++++++-
 .../feel/language-guide/feel-temporal-expressions.md |  3 +++
 .../feel-built-in-functions-conversion.md            | 11 +++++++++++
 .../feel-built-in-functions-string.md                | 12 +++++++++++-
 .../feel/language-guide/feel-temporal-expressions.md |  3 +++
 .../feel-built-in-functions-conversion.md            | 11 +++++++++++
 .../feel-built-in-functions-string.md                | 12 +++++++++++-
 .../feel/language-guide/feel-temporal-expressions.md |  3 +++
 15 files changed, 125 insertions(+), 5 deletions(-)

diff --git a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index 2d25770805..aaa04fb945 100644
--- a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
diff --git a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index 32b931e2b6..59995c4800 100644
--- a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)
diff --git a/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md b/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 84625be793..3ace1ca014 100644
--- a/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,6 +40,9 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
+`@"2024-06-31"` that is invalid because June has only 30 days.
+
 ### Addition
 
 Adds a value to another value. The operator is defined for the followings types.
diff --git a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index 2d25770805..aaa04fb945 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
diff --git a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index a00122e390..4ea20e7659 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)
diff --git a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
index ef362c84cf..265bc1cf2a 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,6 +40,9 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
+`@"2024-06-31"` that is invalid because June has only 30 days.
+
 ### Addition
 
 <table>
diff --git a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index 2d25770805..aaa04fb945 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
diff --git a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index a00122e390..4ea20e7659 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)
diff --git a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 84625be793..3ace1ca014 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,6 +40,9 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
+`@"2024-06-31"` that is invalid because June has only 30 days.
+
 ### Addition
 
 Adds a value to another value. The operator is defined for the followings types.
diff --git a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index 2d25770805..aaa04fb945 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
diff --git a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index a00122e390..4ea20e7659 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)
diff --git a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 84625be793..3ace1ca014 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,6 +40,9 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
+`@"2024-06-31"` that is invalid because June has only 30 days.
+
 ### Addition
 
 Adds a value to another value. The operator is defined for the followings types.
diff --git a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index 2d25770805..aaa04fb945 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
diff --git a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index a00122e390..4ea20e7659 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)
diff --git a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 84625be793..3ace1ca014 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,6 +40,9 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
+`@"2024-06-31"` that is invalid because June has only 30 days.
+
 ### Addition
 
 Adds a value to another value. The operator is defined for the followings types.

From 5eb233f7a9c3490f9d9fe203e3e87310a15b837f Mon Sep 17 00:00:00 2001
From: Philipp Ossler <philipp.ossler@gmail.com>
Date: Fri, 30 Aug 2024 14:29:11 +0200
Subject: [PATCH 2/5] feat(feel): Clarify unary-tests behavior

Extend the description when a unary-tests expression is fulfilled. Make it explicit what an expression with the special variable `?` must evaluate to true.
---
 .../modeler/feel/language-guide/feel-unary-tests.md | 13 +++++++------
 .../modeler/feel/language-guide/feel-unary-tests.md | 13 +++++++------
 .../modeler/feel/language-guide/feel-unary-tests.md | 13 +++++++------
 .../modeler/feel/language-guide/feel-unary-tests.md | 13 +++++++------
 .../modeler/feel/language-guide/feel-unary-tests.md | 13 +++++++------
 5 files changed, 35 insertions(+), 30 deletions(-)

diff --git a/docs/components/modeler/feel/language-guide/feel-unary-tests.md b/docs/components/modeler/feel/language-guide/feel-unary-tests.md
index 3c66b8bf92..6c168f39d7 100644
--- a/docs/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/docs/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -129,13 +129,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
+When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"
diff --git a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md
index 8d2a3a0482..4763e3c53f 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -128,13 +128,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/docs/components/modeler/feel/language-guide/feel-functions#invocation).
+When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"
diff --git a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md
index 8d00e20121..6c168f39d7 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -129,13 +129,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/docs/components/modeler/feel/language-guide/feel-functions#invocation).
+When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"
diff --git a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md
index 8d00e20121..6c168f39d7 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -129,13 +129,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/docs/components/modeler/feel/language-guide/feel-functions#invocation).
+When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"
diff --git a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md
index 3c66b8bf92..6c168f39d7 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -129,13 +129,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
+When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"

From 8fc99535973325686c085a1dc2982a953aed427f Mon Sep 17 00:00:00 2001
From: Philipp Ossler <philipp.ossler@gmail.com>
Date: Thu, 5 Sep 2024 09:24:07 +0200
Subject: [PATCH 3/5] docs: Improve wording

Co-authored-by: Nicola Puppa <72783243+nicpuppa@users.noreply.github.com>
---
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../feel/language-guide/feel-temporal-expressions.md        | 2 +-
 .../modeler/feel/language-guide/feel-unary-tests.md         | 2 +-
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../feel/language-guide/feel-temporal-expressions.md        | 2 +-
 .../modeler/feel/language-guide/feel-unary-tests.md         | 2 +-
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../feel/language-guide/feel-temporal-expressions.md        | 2 +-
 .../modeler/feel/language-guide/feel-unary-tests.md         | 2 +-
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../feel/language-guide/feel-temporal-expressions.md        | 2 +-
 .../modeler/feel/language-guide/feel-unary-tests.md         | 2 +-
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../feel/language-guide/feel-temporal-expressions.md        | 2 +-
 .../modeler/feel/language-guide/feel-unary-tests.md         | 2 +-
 15 files changed, 25 insertions(+), 25 deletions(-)

diff --git a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index aaa04fb945..a95727dbcb 100644
--- a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md b/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 3ace1ca014..accf49e3ac 100644
--- a/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -41,7 +41,7 @@ duration("P3M")
 ```
 
 The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` that is invalid because June has only 30 days.
+`@"2024-06-31"` which is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/docs/components/modeler/feel/language-guide/feel-unary-tests.md b/docs/components/modeler/feel/language-guide/feel-unary-tests.md
index 6c168f39d7..756853e053 100644
--- a/docs/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/docs/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -129,7 +129,7 @@ not(2, 3)
 
 ### Expressions
 
-When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
 such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
 In the expression, the input value can be accessed by the special variable `?`.
diff --git a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index aaa04fb945..a95727dbcb 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 265bc1cf2a..f2c8e43650 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -41,7 +41,7 @@ duration("P3M")
 ```
 
 The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` that is invalid because June has only 30 days.
+`@"2024-06-31"` which is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md
index 4763e3c53f..b271c1666f 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -128,7 +128,7 @@ not(2, 3)
 
 ### Expressions
 
-When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
 such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
 In the expression, the input value can be accessed by the special variable `?`.
diff --git a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index aaa04fb945..a95727dbcb 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 3ace1ca014..accf49e3ac 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -41,7 +41,7 @@ duration("P3M")
 ```
 
 The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` that is invalid because June has only 30 days.
+`@"2024-06-31"` which is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md
index 6c168f39d7..756853e053 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -129,7 +129,7 @@ not(2, 3)
 
 ### Expressions
 
-When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
 such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
 In the expression, the input value can be accessed by the special variable `?`.
diff --git a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index aaa04fb945..a95727dbcb 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 3ace1ca014..accf49e3ac 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -41,7 +41,7 @@ duration("P3M")
 ```
 
 The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` that is invalid because June has only 30 days.
+`@"2024-06-31"` which is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md
index 6c168f39d7..756853e053 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -129,7 +129,7 @@ not(2, 3)
 
 ### Expressions
 
-When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
 such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
 In the expression, the input value can be accessed by the special variable `?`.
diff --git a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index aaa04fb945..a95727dbcb 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` that is invalid because June has
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` that is invalid because
+Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` that is invalid because
+Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
index 3ace1ca014..accf49e3ac 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -41,7 +41,7 @@ duration("P3M")
 ```
 
 The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` that is invalid because June has only 30 days.
+`@"2024-06-31"` which is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md
index 6c168f39d7..756853e053 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-unary-tests.md
@@ -129,7 +129,7 @@ not(2, 3)
 
 ### Expressions
 
-When a unary operator is not enough to express the condition, any expression can be used that returns a boolean value,
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
 such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
 In the expression, the input value can be accessed by the special variable `?`.

From 9c7d6fa681eb214221bf07d3d18fd97924d6ccce Mon Sep 17 00:00:00 2001
From: Philipp Ossler <philipp.ossler@gmail.com>
Date: Thu, 5 Sep 2024 11:17:18 +0200
Subject: [PATCH 4/5] docs: Improve wording

Co-authored-by: Mark Sellings <mark.sellings@camunda.com>
---
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../builtin-functions/feel-built-in-functions-string.md     | 2 +-
 .../feel/language-guide/feel-temporal-expressions.md        | 5 ++---
 3 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index a95727dbcb..6522611d83 100644
--- a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index 59995c4800..3d0bbe0fc7 100644
--- a/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -30,7 +30,7 @@ substring("foobar", -2)
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
 the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
diff --git a/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md b/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
index accf49e3ac..a8ba21dcaf 100644
--- a/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/docs/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,12 +40,11 @@ duration("P3M")
 @"P3M"
 ```
 
-The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` which is invalid because June has only 30 days.
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
 
 ### Addition
 
-Adds a value to another value. The operator is defined for the followings types.
+Adds a value to another value. The operator is defined for the following types.
 
 If a value has a different type, the result is `null`.
 

From 0c06f6c8bf83d9e6bdccf0856b59b8b10a07c0d5 Mon Sep 17 00:00:00 2001
From: Philipp Ossler <philipp.ossler@gmail.com>
Date: Thu, 5 Sep 2024 11:21:32 +0200
Subject: [PATCH 5/5] docs: Improve wording

---
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../builtin-functions/feel-built-in-functions-string.md     | 2 +-
 .../feel/language-guide/feel-temporal-expressions.md        | 3 +--
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../builtin-functions/feel-built-in-functions-string.md     | 2 +-
 .../feel/language-guide/feel-temporal-expressions.md        | 3 +--
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../builtin-functions/feel-built-in-functions-string.md     | 2 +-
 .../feel/language-guide/feel-temporal-expressions.md        | 3 +--
 .../builtin-functions/feel-built-in-functions-conversion.md | 6 +++---
 .../builtin-functions/feel-built-in-functions-string.md     | 2 +-
 .../feel/language-guide/feel-temporal-expressions.md        | 3 +--
 12 files changed, 20 insertions(+), 24 deletions(-)

diff --git a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index a95727dbcb..6522611d83 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index 4ea20e7659..59308327d0 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -30,7 +30,7 @@ substring("foobar", -2)
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
 the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
diff --git a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
index f2c8e43650..9d90e4bdbf 100644
--- a/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,8 +40,7 @@ duration("P3M")
 @"P3M"
 ```
 
-The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` which is invalid because June has only 30 days.
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index a95727dbcb..6522611d83 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index 4ea20e7659..59308327d0 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -30,7 +30,7 @@ substring("foobar", -2)
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
 the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
diff --git a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
index accf49e3ac..bf7ce7cc2b 100644
--- a/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,8 +40,7 @@ duration("P3M")
 @"P3M"
 ```
 
-The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` which is invalid because June has only 30 days.
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index a95727dbcb..6522611d83 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index 4ea20e7659..59308327d0 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -30,7 +30,7 @@ substring("foobar", -2)
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
 the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
diff --git a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
index accf49e3ac..bf7ce7cc2b 100644
--- a/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.4/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,8 +40,7 @@ duration("P3M")
 @"P3M"
 ```
 
-The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` which is invalid because June has only 30 days.
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
 
 ### Addition
 
diff --git a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
index a95727dbcb..6522611d83 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md
@@ -74,7 +74,7 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31"` which is invalid because June has
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
 only 30 days.
 
 **Function signature**
@@ -105,7 +105,7 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
-Returns `null` if the components don't represent a valid calendar date, for example, `2024,6,31` which is invalid because
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
 June has only 30 days.
 
 **Function signature**
@@ -187,7 +187,7 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
-Returns `null` if the string is not a valid calendar date, for example, `"2024-06-31T10:00:00"` which is invalid because
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
 June has only 30 days.
 
 **Function signature**
diff --git a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
index 4ea20e7659..59308327d0 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md
@@ -30,7 +30,7 @@ substring("foobar", -2)
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position` with the given `length`. If `length` is greater than
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
 the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
diff --git a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
index accf49e3ac..bf7ce7cc2b 100644
--- a/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
+++ b/versioned_docs/version-8.5/components/modeler/feel/language-guide/feel-temporal-expressions.md
@@ -40,8 +40,7 @@ duration("P3M")
 @"P3M"
 ```
 
-The value is `null` if a date or date and time literal doesn't represent a valid calendar date, for example,
-`@"2024-06-31"` which is invalid because June has only 30 days.
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
 
 ### Addition