[ES|QL] Trig & hyperbolic function finishing pass (elastic#103205)

Relates to elastic#100558 These functions were mostly done already. I added descriptions and argument descriptions for most of them, otherwise not much work.
droberts195 · Dec 8, 2023 · 690a8a2 · 690a8a2
1 parent cf7941f
commit 690a8a2
Show file tree

Hide file tree

Showing 11 changed files with 48 additions and 23 deletions.
diff --git a/docs/reference/esql/functions/cos.asciidoc b/docs/reference/esql/functions/cos.asciidoc
@@ -4,7 +4,7 @@
 [.text-center]
 image::esql/functions/signature/cos.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Cosine] trigonometric function.
+https://en.wikipedia.org/wiki/Sine_and_cosine[Cosine] trigonometric function. Input expected in radians.
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/functions/sin.asciidoc b/docs/reference/esql/functions/sin.asciidoc
@@ -4,7 +4,7 @@
 [.text-center]
 image::esql/functions/signature/sin.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Sine] trigonometric function.
+https://en.wikipedia.org/wiki/Sine_and_cosine[Sine] trigonometric function. Input expected in radians.
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/functions/tan.asciidoc b/docs/reference/esql/functions/tan.asciidoc
@@ -4,7 +4,7 @@
 [.text-center]
 image::esql/functions/signature/tan.svg[Embedded,opts=inline]
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Tangent] trigonometric function.
+https://en.wikipedia.org/wiki/Sine_and_cosine[Tangent] trigonometric function. Input expected in radians.
 
 [source.merge.styled,esql]
 ----

diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/show.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/show.csv-spec
@@ -6,7 +6,7 @@ v:long
 ;
 
 # TODO: switch this test to ``&format=csv&delimiter=|` output
-showFunctions#[skip:-8.11.99]
+showFunctions#[skip:-8.12.99]
 show functions;
 
        name:keyword      |                        synopsis:keyword          |       argNames:keyword  | argTypes:keyword |             argDescriptions:keyword                |returnType:keyword   |    description:keyword  | optionalArgs:boolean | variadic:boolean                
@@ -22,8 +22,8 @@ ceil                     |"? ceil(n:integer|long|double|unsigned_long)"     |n
 cidr_match               |? cidr_match(arg1:?, arg2...:?)                         |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | true
 coalesce                 |? coalesce(arg1:?, arg2...:?)                           |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | true
 concat                   |? concat(arg1:?, arg2...:?)                             |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | true
-cos                      |"double cos(n:integer|long|double|unsigned_long)"      |n                        |"integer|long|double|unsigned_long"                 | ""                                                 |double                    | ""                      | false                | false
-cosh                     |"double cosh(n:integer|long|double|unsigned_long)"     |n                        |"integer|long|double|unsigned_long"                 | ""                                                 |double                    | ""                      | false                | false
+cos                      |"double cos(n:integer|long|double|unsigned_long)"      |n                        |"integer|long|double|unsigned_long"                 | "An angle, in radians"  |double         | "Returns the trigonometric cosine of an angle"                      | false                | false
+cosh                     |"double cosh(n:integer|long|double|unsigned_long)"     |n                        |"integer|long|double|unsigned_long"                 | "The number who's hyperbolic cosine is to be returned" |double                    | "Returns the hyperbolic cosine of a number"                      | false                | false
 count                    |? count(arg1:?)                                         |arg1                     |?                 | ""                                                 |?                    | ""                      | false                | false
 count_distinct           |? count_distinct(arg1:?, arg2:?)                        |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | false
 date_extract             |? date_extract(arg1:?, arg2:?)                          |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | false
@@ -63,14 +63,14 @@ right                    |"? right(string:keyword, length:integer)"     |[string
 round                    |? round(arg1:?, arg2:?)                                 |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | false
 rtrim                    |"keyword|text rtrim(str:keyword|text)"                  |str                      |"keyword|text"    | ""                                                 |"keyword|text"       |Removes trailing whitespaces from a string.| false | false
 sin                      |"double sin(n:integer|long|double|unsigned_long)" |n                        |"integer|long|double|unsigned_long"           |An angle, in radians                                |double               |Returns the trigonometric sine of an angle  | false      | false
-sinh                     |"double sinh(n:integer|long|double|unsigned_long)"|n                        |"integer|long|double|unsigned_long"           | ""                                                 |double                    | ""                      | false                | false
+sinh                     |"double sinh(n:integer|long|double|unsigned_long)"|n                        |"integer|long|double|unsigned_long"           | "The number to return the hyperbolic sine of"      |double                    | "Returns the hyperbolic sine of a number"                      | false                | false
 split                    |? split(arg1:?, arg2:?)                                 |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | false
 sqrt                     |"? sqrt(n:integer|long|double|unsigned_long)"     |n                        |"integer|long|double|unsigned_long"                 | ""                                                 |?                    | ""                      | false                | false
 starts_with              |? starts_with(arg1:?, arg2:?)                           |[arg1, arg2]             |[?, ?]            |["", ""]                                            |?                    | ""                      | [false, false]       | false
 substring                |? substring(arg1:?, arg2:?, arg3:?)                     |[arg1, arg2, arg3]       |[?, ?, ?]         |["", "", ""]                                        |?                    | ""                      | [false, false, false]| false
 sum                      |? sum(arg1:?)                                           |arg1                     |?                 | ""                                                 |?                    | ""                      | false                | false
-tan                      |"double tan(n:integer|long|double|unsigned_long)"      |n                        |"integer|long|double|unsigned_long"           | ""                      |double               | ""                      | false                | false
-tanh                     |"double tanh(n:integer|long|double|unsigned_long)"     |n                        |"integer|long|double|unsigned_long"           | ""                      |double               | ""                      | false                | false
+tan                      |"double tan(n:integer|long|double|unsigned_long)"      |n                        |"integer|long|double|unsigned_long"           | "An angle, in radians"  |double               | "Returns the trigonometric tangent of an angle"                      | false                | false
+tanh                     |"double tanh(n:integer|long|double|unsigned_long)"     |n                        |"integer|long|double|unsigned_long"           | "The number to return the hyperbolic tangent of" |double               | "Returns the hyperbolic tangent of a number"                      | false                | false
 tau                      |? tau()                                                 | null                    | null             | null                                               |?                    | ""                      | null                 | false
 to_bool                  |"boolean to_bool(v:boolean|keyword|text|double|long|unsigned_long|integer)"                      |v   |"boolean|keyword|text|double|long|unsigned_long|integer"                                                   |                                                    |boolean                          |                                                                                       |false                       |false          
 to_boolean               |"boolean to_boolean(v:boolean|keyword|text|double|long|unsigned_long|integer)"                   |v   |"boolean|keyword|text|double|long|unsigned_long|integer"                                                   |                                                    |boolean                          |                                                                                       |false                       |false          

diff --git a/.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cos.java b/.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cos.java
@@ -21,8 +21,11 @@
  * Cosine trigonometric function.
  */
 public class Cos extends AbstractTrigonometricFunction {
-    @FunctionInfo(returnType = "double")
-    public Cos(Source source, @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }) Expression n) {
+    @FunctionInfo(returnType = "double", description = "Returns the trigonometric cosine of an angle")
+    public Cos(
+        Source source,
+        @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }, description = "An angle, in radians") Expression n
+    ) {
         super(source, n);
     }
 

diff --git a/...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cosh.java b/...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Cosh.java
@@ -21,8 +21,15 @@
  * Cosine hyperbolic function.
  */
 public class Cosh extends AbstractTrigonometricFunction {
-    @FunctionInfo(returnType = "double")
-    public Cosh(Source source, @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }) Expression n) {
+    @FunctionInfo(returnType = "double", description = "Returns the hyperbolic cosine of a number")
+    public Cosh(
+        Source source,
+        @Param(
+            name = "n",
+            type = { "integer", "long", "double", "unsigned_long" },
+            description = "The number who's hyperbolic cosine is to be returned"
+        ) Expression n
+    ) {
         super(source, n);
     }
 

diff --git a/...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Sinh.java b/...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Sinh.java
@@ -21,8 +21,15 @@
  * Sine hyperbolic function.
  */
 public class Sinh extends AbstractTrigonometricFunction {
-    @FunctionInfo(returnType = "double")
-    public Sinh(Source source, @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }) Expression n) {
+    @FunctionInfo(returnType = "double", description = "Returns the hyperbolic sine of a number")
+    public Sinh(
+        Source source,
+        @Param(
+            name = "n",
+            type = { "integer", "long", "double", "unsigned_long" },
+            description = "The number to return the hyperbolic sine of"
+        ) Expression n
+    ) {
         super(source, n);
     }
 

diff --git a/.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tan.java b/.../esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tan.java
@@ -21,8 +21,11 @@
  * Tangent trigonometric function.
  */
 public class Tan extends AbstractTrigonometricFunction {
-    @FunctionInfo(returnType = "double")
-    public Tan(Source source, @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }) Expression n) {
+    @FunctionInfo(returnType = "double", description = "Returns the trigonometric tangent of an angle")
+    public Tan(
+        Source source,
+        @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }, description = "An angle, in radians") Expression n
+    ) {
         super(source, n);
     }
 

diff --git a/...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tanh.java b/...esql/src/main/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/Tanh.java
@@ -21,8 +21,15 @@
  * Tangent hyperbolic function.
  */
 public class Tanh extends AbstractTrigonometricFunction {
-    @FunctionInfo(returnType = "double")
-    public Tanh(Source source, @Param(name = "n", type = { "integer", "long", "double", "unsigned_long" }) Expression n) {
+    @FunctionInfo(returnType = "double", description = "Returns the hyperbolic tangent of a number")
+    public Tanh(
+        Source source,
+        @Param(
+            name = "n",
+            type = { "integer", "long", "double", "unsigned_long" },
+            description = "The number to return the hyperbolic tangent of"
+        ) Expression n
+    ) {
         super(source, n);
     }
 

diff --git a/...src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CoshTests.java b/...src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/CoshTests.java
@@ -33,7 +33,6 @@ public static Iterable<Object[]> parameters() {
             710d,  // Hyperbolic Cosine grows extremely fast. Values outside this range return Double.POSITIVE_INFINITY
             List.of()
         );
-        suppliers = anyNullIsNull(true, suppliers);
 
         // Out of range cases
         suppliers.addAll(
@@ -62,7 +61,7 @@ public static Iterable<Object[]> parameters() {
                 )
             )
         );
-        return parameterSuppliersFromTypedData(errorsForCasesWithoutExamples(suppliers));
+        return parameterSuppliersFromTypedData(errorsForCasesWithoutExamples(anyNullIsNull(true, suppliers)));
     }
 
     @Override

diff --git a/...src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/SinhTests.java b/...src/test/java/org/elasticsearch/xpack/esql/expression/function/scalar/math/SinhTests.java
@@ -33,7 +33,6 @@ public static Iterable<Object[]> parameters() {
             710d,  // Hyperbolic sine grows extremely fast. Values outside this range return Double.POSITIVE_INFINITY
             List.of()
         );
-        suppliers = anyNullIsNull(true, suppliers);
 
         // Out of range cases
         suppliers.addAll(
@@ -62,7 +61,7 @@ public static Iterable<Object[]> parameters() {
                 )
             )
         );
-        return parameterSuppliersFromTypedData(errorsForCasesWithoutExamples(suppliers));
+        return parameterSuppliersFromTypedData(errorsForCasesWithoutExamples(anyNullIsNull(true, suppliers)));
     }
 
     @Override