ESQL: Improve tests and docs for some functions (#107331)

This improves the tests and docs for a few functions, specifically `E`,
`FLOOR`, `PI`, `POW`, and `ROUND`. The examples and tested signatures
will get copied into the docs and kibana signatures.


Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com>

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

@@ -2,4 +2,4 @@
 
 *Description*
 
-Euler’s number.
+Returns {wikipedia}/E_(mathematical_constant)[Euler's number].

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

@@ -3,3 +3,7 @@
 *Description*
 
 Round a number down to the nearest integer.
+
+NOTE: This is a noop for `long` (including unsigned) and `integer`.
+For `double` this picks the closest `double` value to the integer
+similar to {javadoc}/java.base/java/lang/Math.html#floor(double)[Math.floor].

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

@@ -2,4 +2,4 @@
 
 *Description*
 
-The ratio of a circle’s circumference to its diameter.
+Returns the {wikipedia}/Pi[ratio] of a circle's circumference to its diameter.

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

@@ -2,4 +2,6 @@
 
 *Description*
 
-Returns the value of a base raised to the power of an exponent.
+Returns the value of `base` raised to the power of `exponent`.
+
+NOTE: It is still possible to overflow a double result here; in that case, null will be returned.

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

@@ -2,4 +2,4 @@
 
 *Description*
 
-Rounds a number to the closest number with the specified number of digits.
+Rounds a number to the closest number with the specified number of digits. Defaults to 0 digits if no number of digits is provided. If the specified number of digits is negative, rounds to the number of digits left of the decimal point.

docs/reference/esql/functions/e.asciidoc → docs/reference/esql/functions/examples/e.asciidoc

@@ -1,15 +1,4 @@
-[discrete]
-[[esql-e]]
-=== `E`
-
-*Syntax*
-
-[.text-center]
-image::esql/functions/signature/e.svg[Embedded,opts=inline]
-
-*Description*
-
-Returns {wikipedia}/E_(mathematical_constant)[Euler's number].
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
 
 *Example*
 
@@ -21,3 +10,4 @@ include::{esql-specs}/math.csv-spec[tag=e]
 |===
 include::{esql-specs}/math.csv-spec[tag=e-result]
 |===
+

docs/reference/esql/functions/examples/floor.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=floor]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=floor-result]
+|===
+

docs/reference/esql/functions/examples/pi.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/math.csv-spec[tag=pi]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=pi-result]
+|===
+

docs/reference/esql/functions/pow.asciidoc → docs/reference/esql/functions/examples/pow.asciidoc

@@ -1,27 +1,4 @@
-[discrete]
-[[esql-pow]]
-=== `POW`
-
-*Syntax*
-
-[.text-center]
-image::esql/functions/signature/pow.svg[Embedded,opts=inline]
-
-*Parameters*
-
-`base`::
-Numeric expression. If `null`, the function returns `null`.
-
-`exponent`::
-Numeric expression. If `null`, the function returns `null`.
-
-*Description*
-
-Returns the value of `base` raised to the power of `exponent`. Both arguments
-must be numeric. The output is always a double.  Note that it is still possible
-to overflow a double result here; in that case, null will be returned.
-
-include::types/pow.asciidoc[]
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
 
 *Examples*
 
@@ -33,10 +10,8 @@ include::{esql-specs}/math.csv-spec[tag=powDI]
 |===
 include::{esql-specs}/math.csv-spec[tag=powDI-result]
 |===
-
 The exponent can be a fraction, which is similar to performing a root.
 For example, the exponent of `0.5` will give the square root of the base:
-
 [source.merge.styled,esql]
 ----
 include::{esql-specs}/math.csv-spec[tag=powID-sqrt]
@@ -45,3 +20,4 @@ include::{esql-specs}/math.csv-spec[tag=powID-sqrt]
 |===
 include::{esql-specs}/math.csv-spec[tag=powID-sqrt-result]
 |===
+

docs/reference/esql/functions/examples/round.asciidoc

@@ -0,0 +1,13 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.
+
+*Example*
+
+[source.merge.styled,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=round]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/docs.csv-spec[tag=round-result]
+|===
+

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

@@ -2,11 +2,14 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "e",
-  "description" : "Euler’s number.",
+  "description" : "Returns Euler's number.",
   "signatures" : [
     {
       "params" : [ ],
       "returnType" : "double"
     }
+  ],
+  "examples" : [
+    "ROW E()"
   ]
 }

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

@@ -3,14 +3,15 @@
   "type" : "eval",
   "name" : "floor",
   "description" : "Round a number down to the nearest integer.",
+  "note" : "This is a noop for `long` (including unsigned) and `integer`.\nFor `double` this picks the closest `double` value to the integer\nsimilar to Math.floor.",
   "signatures" : [
     {
       "params" : [
         {
           "name" : "number",
           "type" : "double",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
@@ -22,7 +23,7 @@
           "name" : "number",
           "type" : "integer",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
@@ -34,7 +35,7 @@
           "name" : "number",
           "type" : "long",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
@@ -46,11 +47,14 @@
           "name" : "number",
           "type" : "unsigned_long",
           "optional" : false,
-          "description" : ""
+          "description" : "Numeric expression. If `null`, the function returns `null`."
         }
       ],
       "variadic" : false,
       "returnType" : "unsigned_long"
     }
+  ],
+  "examples" : [
+    "ROW a=1.8\n| EVAL a=FLOOR(a)"
   ]
 }

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

@@ -2,11 +2,14 @@
   "comment" : "This is generated by ESQL's AbstractFunctionTestCase. Do no edit it. See ../README.md for how to regenerate it.",
   "type" : "eval",
   "name" : "pi",
-  "description" : "The ratio of a circle’s circumference to its diameter.",
+  "description" : "Returns the ratio of a circle's circumference to its diameter.",
   "signatures" : [
     {
       "params" : [ ],
       "returnType" : "double"
     }
+  ],
+  "examples" : [
+    "ROW PI()"
   ]
 }