ESQL: Generate more docs (elastic#106367)

This modifies the ESQL test infrastructure to generate more of the
documentation for functions. It generates the *Description* section, the
*Examples* section, and the *Parameters* section as separate files so we
can use them as needed. It also generates a `layout` file that's just
a guess as to how to render the whole thing. In some cases it'll work
and we can use that instead of hand maintaining a "top level"
description file for the function.

Most newly generated files are unused. We have to chose to pick them up
by replacing the sections we were manually maintaining with an include
of the generated section. Or by replacing the entire hand maintained
file with the generated top level file.

Relates to elastic#104247

docs/reference/esql/functions/abs.asciidoc

@@ -16,8 +16,6 @@ Numeric expression. If `null`, the function returns `null`.
 
 Returns the absolute value.
 
-*Supported types*
-
 include::types/abs.asciidoc[]
 
 *Examples*
@@ -38,4 +36,4 @@ include::{esql-specs}/math.csv-spec[tag=docsAbsEmployees]
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
 include::{esql-specs}/math.csv-spec[tag=docsAbsEmployees-result]
-|===
+|===

docs/reference/esql/functions/acos.asciidoc

@@ -17,8 +17,6 @@ Numeric expression. If `null`, the function returns `null`.
 Returns the {wikipedia}/Inverse_trigonometric_functions[arccosine] of `n` as an
 angle, expressed in radians.
 
-*Supported types*
-
 include::types/acos.asciidoc[]
 
 *Example*

docs/reference/esql/functions/asin.asciidoc

@@ -17,8 +17,6 @@ Numeric expression. If `null`, the function returns `null`.
 Returns the {wikipedia}/Inverse_trigonometric_functions[arcsine] of the input
 numeric expression as an angle, expressed in radians.
 
-*Supported types*
-
 include::types/asin.asciidoc[]
 
 *Example*

docs/reference/esql/functions/atan.asciidoc

@@ -17,8 +17,6 @@ Numeric expression. If `null`, the function returns `null`.
 Returns the {wikipedia}/Inverse_trigonometric_functions[arctangent] of the input
 numeric expression as an angle, expressed in radians.
 
-*Supported types*
-
 include::types/atan.asciidoc[]
 
 *Example*
@@ -30,4 +28,4 @@ include::{esql-specs}/floats.csv-spec[tag=atan]
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
 include::{esql-specs}/floats.csv-spec[tag=atan-result]
-|===
+|===

docs/reference/esql/functions/atan2.asciidoc

@@ -20,8 +20,6 @@ Numeric expression. If `null`, the function returns `null`.
 The {wikipedia}/Atan2[angle] between the positive x-axis and the ray from the
 origin to the point (x , y) in the Cartesian plane, expressed in radians.
 
-*Supported types*
-
 include::types/atan2.asciidoc[]
 
 *Example*

docs/reference/esql/functions/binary.asciidoc

@@ -23,70 +23,52 @@ include::types/not_equals.asciidoc[]
 [.text-center]
 image::esql/functions/signature/less_than.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/less_than.asciidoc[]
 
 ==== Less than or equal to `<=`
 [.text-center]
 image::esql/functions/signature/less_than_or_equal.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/less_than_or_equal.asciidoc[]
 
 ==== Greater than `>`
 [.text-center]
 image::esql/functions/signature/greater_than.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/greater_than.asciidoc[]
 
 ==== Greater than or equal to `>=`
 [.text-center]
 image::esql/functions/signature/greater_than_or_equal.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/greater_than_or_equal.asciidoc[]
 
 ==== Add `+`
 [.text-center]
 image::esql/functions/signature/add.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/add.asciidoc[]
 
 ==== Subtract `-`
 [.text-center]
 image::esql/functions/signature/sub.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/sub.asciidoc[]
 
 ==== Multiply `*`
 [.text-center]
 image::esql/functions/signature/mul.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/mul.asciidoc[]
 
 ==== Divide `/`
 [.text-center]
 image::esql/functions/signature/div.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/div.asciidoc[]
 
 ==== Modulus `%`
 [.text-center]
 image::esql/functions/signature/mod.svg[Embedded,opts=inline]
 
-Supported types:
-
 include::types/mod.asciidoc[]

docs/reference/esql/functions/ceil.asciidoc

@@ -17,11 +17,9 @@ Numeric expression. If `null`, the function returns `null`.
 Round a number up 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 
+      For `double` this picks the closest `double` value to the integer
       similar to {javadoc}/java.base/java/lang/Math.html#ceil(double)[Math.ceil].
 
-*Supported types*
-
 include::types/ceil.asciidoc[]
 
 

docs/reference/esql/functions/coalesce.asciidoc

@@ -8,24 +8,6 @@
 ----
 COALESCE(expression1 [, ..., expressionN])
 ----
-
-*Parameters*
-
-`expressionX`::
-Expression to evaluate.
-
-*Description*
-
-Returns the first of its arguments that is not null. If all arguments are null,
-it returns `null`.
-
-*Example*
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/null.csv-spec[tag=coalesce]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/null.csv-spec[tag=coalesce-result]
-|===
+include::parameters/coalesce.asciidoc[]
+include::description/coalesce.asciidoc[]
+include::examples/coalesce.asciidoc[]

docs/reference/esql/functions/cos.asciidoc

@@ -17,8 +17,6 @@ Numeric expression. If `null`, the function returns `null`.
 Returns the {wikipedia}/Sine_and_cosine[cosine] of `n`. Input expected in
 radians.
 
-*Supported types*
-
 include::types/cos.asciidoc[]
 
 *Example*

docs/reference/esql/functions/cosh.asciidoc

@@ -16,8 +16,6 @@ Numeric expression. If `null`, the function returns `null`.
 
 Returns the {wikipedia}/Hyperbolic_functions[hyperbolic cosine].
 
-*Supported types*
-
 include::types/cosh.asciidoc[]
 
 *Example*

docs/reference/esql/functions/date_diff.asciidoc

@@ -46,8 +46,6 @@ s|abbreviations
 | nanosecond  | nanoseconds, ns
 |===
 
-*Supported types*
-
 include::types/date_diff.asciidoc[]
 
 *Example*

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the absolute value.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+The arccosine of an angle, expressed in radians.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Inverse sine trigonometric function.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Inverse tangent trigonometric function.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+The angle between the positive x-axis and the ray from the origin to the point (x , y) in the Cartesian plane.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Creates human-friendly buckets and returns a datetime value for each row that corresponds to the resulting bucket the row falls into.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Accepts pairs of conditions and values. The function returns the value that belongs to the first condition that evaluates to true.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Round a number up to the nearest integer.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the first of its arguments that is not null. If all arguments are null, it returns `null`.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Concatenates two or more strings.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the trigonometric cosine of an angle

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the hyperbolic cosine of a number

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Subtract 2 dates and return their difference in multiples of a unit specified in the 1st argument

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Extracts parts of a date, like year, month, day, hour.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Parses a string into a date value

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Euler’s number.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns a boolean that indicates whether a keyword string ends with another string

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Round a number down to the nearest integer.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the maximum value from many columns.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the minimum value from many columns.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the substring that extracts 'length' chars from 'str' starting from the left.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the character length of a string.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the logarithm of a value to a base.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Returns the log base 10.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Removes leading whitespaces from a string.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Converts a multivalued field into a single valued field containing the average of all of the values.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Reduce a multivalued string field to a single valued field by concatenating all values.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Reduce a multivalued field to a single valued field containing the count of values.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Remove duplicate values from a multivalued field.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Reduce a multivalued field to a single valued field containing the first value.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Reduce a multivalued field to a single valued field containing the last value.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Reduce a multivalued field to a single valued field containing the maximum value.

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

@@ -0,0 +1,5 @@
+// This is generated by ESQL's AbstractFunctionTestCase. Do no edit it.
+
+*Description*
+
+Converts a multivalued field into a single valued field containing the median value.