ESQL: All descriptions are a full sentence (#110791)

This asserts that all functions have descriptions that are complete
sentences.

docs/reference/esql/functions/description/locate.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns an integer that indicates the position of a keyword substring within another string
+Returns an integer that indicates the position of a keyword substring within another string.

docs/reference/esql/functions/description/substring.asciidoc

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns a substring of a string, specified by a start position and an optional length
+Returns a substring of a string, specified by a start position and an optional length.

docs/reference/esql/functions/kibana/definition/locate.json

@@ -2,7 +2,7 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "locate",
-  "description" : "Returns an integer that indicates the position of a keyword substring within another string",
+  "description" : "Returns an integer that indicates the position of a keyword substring within another string.",
   "signatures" : [
     {
       "params" : [

docs/reference/esql/functions/kibana/definition/substring.json

@@ -2,7 +2,7 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "substring",
-  "description" : "Returns a substring of a string, specified by a start position and an optional length",
+  "description" : "Returns a substring of a string, specified by a start position and an optional length.",
   "signatures" : [
     {
       "params" : [

docs/reference/esql/functions/kibana/docs/locate.md

@@ -3,7 +3,7 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### LOCATE
-Returns an integer that indicates the position of a keyword substring within another string
+Returns an integer that indicates the position of a keyword substring within another string.
 
 ```
 row a = "hello"

docs/reference/esql/functions/kibana/docs/substring.md

@@ -3,7 +3,7 @@ This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../READ
 -->
 
 ### SUBSTRING
-Returns a substring of a string, specified by a start position and an optional length
+Returns a substring of a string, specified by a start position and an optional length.
 
 ```
 FROM employees

x-pack/plugin/esql/qa/testFixtures/src/main/resources/meta.csv-spec

@@ -275,7 +275,7 @@ ip_prefix     |Truncates an IP to a given prefix length.
 least         |Returns the minimum value from multiple columns. This is similar to <<esql-mv_min>> except it is intended to run on multiple columns at once.
 left          |Returns the substring that extracts 'length' chars from 'string' starting from the left.
 length        |Returns the character length of a string.
-locate        |Returns an integer that indicates the position of a keyword substring within another string
+locate        |Returns an integer that indicates the position of a keyword substring within another string.
 log           |Returns the logarithm of a value to a base. The input can be any numeric value, the return value is always a double.  Logs of zero, negative numbers, and base of one return `null` as well as a warning.
 log10         |Returns the logarithm of a value to base 10. The input can be any numeric value, the return value is always a double.  Logs of 0 and negative numbers return `null` as well as a warning.
 ltrim         |Removes leading whitespaces from a string.
@@ -320,7 +320,7 @@ st_within     |Returns whether the first geometry is within the second geometry.
 st_x          |Extracts the `x` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `longitude` value.
 st_y          |Extracts the `y` coordinate from the supplied point. If the points is of type `geo_point` this is equivalent to extracting the `latitude` value.
 starts_with   |Returns a boolean that indicates whether a keyword string starts with another string.
-substring     |Returns a substring of a string, specified by a start position and an optional length
+substring     |Returns a substring of a string, specified by a start position and an optional length.
 sum           |The sum of a numeric field.
 tan           |Returns the {wikipedia}/Sine_and_cosine[Tangent] trigonometric function of an angle.
 tanh          |Returns the {wikipedia}/Hyperbolic_functions[Tangent] hyperbolic function of an angle.
@@ -351,7 +351,7 @@ to_unsigned_lo|Converts an input value to an unsigned long value. If the input p
 to_upper      |Returns a new string representing the input string converted to upper case.
 to_ver        |Converts an input string to a version value.
 to_version    |Converts an input string to a version value.
-top      |Collects the top values for a field. Includes repeated values.
+top           |Collects the top values for a field. Includes repeated values.
 trim          |Removes leading and trailing whitespaces from a string.
 values        |Collect values for a field.
 weighted_avg  |The weighted average of a numeric field.

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java

@@ -25,7 +25,7 @@ public @interface FunctionInfo {
 
     /**
      * The description of the function rendered in {@code META FUNCTIONS}
-     * and the docs.
+     * and the docs. These should be complete sentences.
      */
     String description() default "";
 

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Locate.java

@@ -48,7 +48,7 @@ public class Locate extends EsqlScalarFunction implements OptionalArgument {
 
     @FunctionInfo(
         returnType = "integer",
-        description = "Returns an integer that indicates the position of a keyword substring within another string",
+        description = "Returns an integer that indicates the position of a keyword substring within another string.",
         examples = @Example(file = "string", tag = "locate")
     )
     public Locate(

x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java

@@ -48,7 +48,7 @@ public class Substring extends EsqlScalarFunction implements OptionalArgument {
 
     @FunctionInfo(
         returnType = "keyword",
-        description = "Returns a substring of a string, specified by a start position and an optional length",
+        description = "Returns a substring of a string, specified by a start position and an optional length.",
         examples = {
             @Example(file = "docs", tag = "substring", description = "This example returns the first three characters of every last name:"),
             @Example(file = "docs", tag = "substringEnd", description = """

x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java

@@ -80,6 +80,8 @@ import static org.elasticsearch.compute.data.BlockUtils.toJavaObject;
 import static org.elasticsearch.xpack.esql.SerializationTestUtils.assertSerialization;
 import static org.elasticsearch.xpack.esql.core.util.SpatialCoordinateTypes.CARTESIAN;
 import static org.elasticsearch.xpack.esql.core.util.SpatialCoordinateTypes.GEO;
+import static org.hamcrest.Matchers.either;
+import static org.hamcrest.Matchers.endsWith;
 import static org.hamcrest.Matchers.equalTo;
 import static org.hamcrest.Matchers.hasSize;
 import static org.hamcrest.Matchers.instanceOf;
@@ -349,6 +351,12 @@ public abstract class AbstractFunctionTestCase extends ESTestCase {
         List<EsqlFunctionRegistry.ArgSignature> args = description.args();
 
         assertTrue("expect description to be defined", description.description() != null && false == description.description().isEmpty());
+        assertThat(
+            "descriptions should be complete sentences",
+            description.description(),
+            either(endsWith(".")) // A full sentence
+                .or(endsWith("∅")) // Math
+        );
 
         List<Set<String>> typesFromSignature = new ArrayList<>();
         Set<String> returnFromSignature = new HashSet<>();