From 55532c8d6fd2503af5e13f3ee1aae3be374d2bdf Mon Sep 17 00:00:00 2001 From: Nik Everett Date: Thu, 11 Jul 2024 16:44:15 -0400 Subject: [PATCH] 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 +- .../esql/functions/description/substring.asciidoc | 2 +- .../esql/functions/kibana/definition/locate.json | 2 +- .../esql/functions/kibana/definition/substring.json | 2 +- docs/reference/esql/functions/kibana/docs/locate.md | 2 +- docs/reference/esql/functions/kibana/docs/substring.md | 2 +- .../esql/qa/testFixtures/src/main/resources/meta.csv-spec | 6 +++--- .../xpack/esql/expression/function/FunctionInfo.java | 2 +- .../esql/expression/function/scalar/string/Locate.java | 2 +- .../esql/expression/function/scalar/string/Substring.java | 2 +- .../expression/function/AbstractFunctionTestCase.java | 8 ++++++++ 11 files changed, 20 insertions(+), 12 deletions(-) diff --git a/docs/reference/esql/functions/description/locate.asciidoc b/docs/reference/esql/functions/description/locate.asciidoc index 60a6d435e37b6..e5a6fba512432 100644 --- a/docs/reference/esql/functions/description/locate.asciidoc +++ b/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. diff --git a/docs/reference/esql/functions/description/substring.asciidoc b/docs/reference/esql/functions/description/substring.asciidoc index edb97b219bbe0..3d8091f26c04d 100644 --- a/docs/reference/esql/functions/description/substring.asciidoc +++ b/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. diff --git a/docs/reference/esql/functions/kibana/definition/locate.json b/docs/reference/esql/functions/kibana/definition/locate.json index 13b7512e17def..2097c90b41958 100644 --- a/docs/reference/esql/functions/kibana/definition/locate.json +++ b/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" : [ diff --git a/docs/reference/esql/functions/kibana/definition/substring.json b/docs/reference/esql/functions/kibana/definition/substring.json index 25f432796cc8d..b38b545822a90 100644 --- a/docs/reference/esql/functions/kibana/definition/substring.json +++ b/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" : [ diff --git a/docs/reference/esql/functions/kibana/docs/locate.md b/docs/reference/esql/functions/kibana/docs/locate.md index 7fffbfd548f20..75275068d3096 100644 --- a/docs/reference/esql/functions/kibana/docs/locate.md +++ b/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" diff --git a/docs/reference/esql/functions/kibana/docs/substring.md b/docs/reference/esql/functions/kibana/docs/substring.md index 62c4eb33c2e95..5f2601a279f6f 100644 --- a/docs/reference/esql/functions/kibana/docs/substring.md +++ b/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 diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/meta.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/meta.csv-spec index e7fa027ff1d6e..f44f1041a6800 100644 --- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/meta.csv-spec +++ b/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 <> 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. diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java index 98c191eddfb06..801d18b7a3801 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java +++ b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/FunctionInfo.java @@ -25,7 +25,7 @@ /** * The description of the function rendered in {@code META FUNCTIONS} - * and the docs. + * and the docs. These should be complete sentences. */ String description() default ""; diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Locate.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Locate.java index 54d8c32d4d467..ea088bdc412e8 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Locate.java +++ b/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( diff --git a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java b/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java index 7e03b3e821f20..7c2ecd0c60e49 100644 --- a/x-pack/plugin/esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/string/Substring.java +++ b/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 = """ diff --git a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java index 80dc2e434ab0f..f2ca17e2743bb 100644 --- a/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java +++ b/x-pack/plugin/esql/src/test/java/org/elasticsearch/xpack/esql/expression/function/AbstractFunctionTestCase.java @@ -80,6 +80,8 @@ 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 static void testFunctionInfo() { List 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> typesFromSignature = new ArrayList<>(); Set returnFromSignature = new HashSet<>();