ESQL: Fixup docs for LOG and LOG10 (#106963)

This merges all of the hand written docs for `LOG` and `LOG10` into the
annotations which updates the `META FUNCTIONS` - now it'll always be the
same as the docs. This also deletes the hand maintained docs and let's
the documentation generation process rebuild it.

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

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns the logarithm of a number to a base.
+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.

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

@@ -2,4 +2,4 @@
 
 *Description*
 
-Returns the log base 10.
+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.

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

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

docs/reference/esql/functions/examples/log10.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=log10]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/math.csv-spec[tag=log10-result]
+|===
+

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

@@ -12,3 +12,4 @@ image::esql/functions/signature/log.svg[Embedded,opts=inline]
 include::../parameters/log.asciidoc[]
 include::../description/log.asciidoc[]
 include::../types/log.asciidoc[]
+include::../examples/log.asciidoc[]

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

@@ -12,3 +12,4 @@ image::esql/functions/signature/log10.svg[Embedded,opts=inline]
 include::../parameters/log10.asciidoc[]
 include::../description/log10.asciidoc[]
 include::../types/log10.asciidoc[]
+include::../examples/log10.asciidoc[]

docs/reference/esql/functions/log.asciidoc

@@ -1,46 +0,0 @@
-[discrete]
-[[esql-log]]
-=== `LOG`
-
-*Syntax*
-
-[source,esql]
-----
-LOG([base,] value)
-----
-
-*Parameters*
-
-`base`::
-Numeric expression. If `null`, the function returns `null`. The base is an optional input parameter. If a base is not provided, this function returns the natural logarithm (base e) of a value.
-
-`value`::
-Numeric expression. If `null`, the function returns `null`.
-
-*Description*
-
-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, infinites and base of one return `null` as well as a warning.
-
-include::types/log.asciidoc[]
-
-*Example*
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/math.csv-spec[tag=log]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/math.csv-spec[tag=log-result]
-|===
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/math.csv-spec[tag=logUnary]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/math.csv-spec[tag=logUnary-result]
-|===

docs/reference/esql/functions/log10.asciidoc

@@ -1,31 +0,0 @@
-[discrete]
-[[esql-log10]]
-=== `LOG10`
-
-*Syntax*
-
-[.text-center]
-image::esql/functions/signature/log10.svg[Embedded,opts=inline]
-
-`n`::
-Numeric expression. If `null`, the function returns `null`.
-
-*Description*
-
-Returns the logarithm to base 10. The input can be any numeric value, the return
-value is always a double.
-
-Logs of 0, negative numbers, and infinites return `null` as well as a warning.
-
-include::types/log10.asciidoc[]
-
-*Example*
-
-[source.merge.styled,esql]
-----
-include::{esql-specs}/math.csv-spec[tag=log10]
-----
-[%header.monospaced.styled,format=dsv,separator=|]
-|===
-include::{esql-specs}/math.csv-spec[tag=log10-result]
-|===

docs/reference/esql/functions/math-functions.asciidoc

@@ -41,8 +41,8 @@ include::layout/cos.asciidoc[]
 include::layout/cosh.asciidoc[]
 include::e.asciidoc[]
 include::floor.asciidoc[]
-include::log.asciidoc[]
-include::log10.asciidoc[]
+include::layout/log.asciidoc[]
+include::layout/log10.asciidoc[]
 include::pi.asciidoc[]
 include::pow.asciidoc[]
 include::round.asciidoc[]

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

@@ -3,7 +3,7 @@
 *Parameters*
 
 `base`::
-
+Base of logarithm. If `null`, the function returns `null`. If not provided, this function returns the natural logarithm (base e) of a value.
 
 `number`::
-
+Numeric expression. If `null`, the function returns `null`.

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

@@ -3,4 +3,4 @@
 *Parameters*
 
 `number`::
-
+Numeric expression. If `null`, the function returns `null`.

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

@@ -137,8 +137,8 @@ greatest      |first                               |"integer|long|double|boolean
 least         |first                               |"integer|long|double|boolean|keyword|text|ip|version"                                                                             |[""]
 left          |[string, length]                    |["keyword|text", integer]                                                                                                         |[The string from which to return a substring., The number of characters to return.]
 length        |string                              |"keyword|text"                                                                                                                    |[""]
-log           |[base, number]                      |["integer|unsigned_long|long|double", "integer|unsigned_long|long|double"]                                                        |[, ]
-log10         |number                              |"double|integer|long|unsigned_long"                                                                                               |[""]
+log           |[base, number]                      |["integer|unsigned_long|long|double", "integer|unsigned_long|long|double"]                                                        |["Base of logarithm. If `null`\, the function returns `null`. If not provided\, this function returns the natural logarithm (base e) of a value.", "Numeric expression. If `null`\, the function returns `null`."]
+log10         |number                              |"double|integer|long|unsigned_long"                                                                                               |Numeric expression. If `null`, the function returns `null`.
 ltrim         |string                              |"keyword|text"                                                                                                                    |[""]
 max           |number                              |"double|integer|long"                                                                                                             |[""]
 median        |number                              |"double|integer|long"                                                                                                             |[""]
@@ -245,8 +245,8 @@ greatest      |Returns the maximum value from many columns.
 least         |Returns the minimum value from many columns.
 left          |Returns the substring that extracts 'length' chars from 'string' starting from the left.
 length        |Returns the character length of a string.
-log           |Returns the logarithm of a number to a base.
-log10         |Returns the log base 10.
+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.
 max           |The maximum value of a numeric field.
 median        |The value that is greater than half of all values and less than half of all values.

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

@@ -9,6 +9,7 @@ package org.elasticsearch.xpack.esql.expression.function.scalar.math;
 
 import org.elasticsearch.compute.ann.Evaluator;
 import org.elasticsearch.compute.operator.EvalOperator.ExpressionEvaluator;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.expression.function.scalar.EsqlScalarFunction;
@@ -32,11 +33,28 @@ public class Log extends EsqlScalarFunction implements OptionalArgument {
 
     private final Expression base, value;
 
-    @FunctionInfo(returnType = "double", description = "Returns the logarithm of a number to a base.")
+    @FunctionInfo(
+        returnType = "double",
+        description = "Returns the logarithm of a value to a base. The input can be any numeric value, "
+            + "the return value is always a double.\n"
+            + "\n"
+            + "Logs of zero, negative numbers, and base of one return `null` as well as a warning.",
+        examples = { @Example(file = "math", tag = "log"), @Example(file = "math", tag = "logUnary") }
+    )
     public Log(
         Source source,
-        @Param(name = "base", type = { "integer", "unsigned_long", "long", "double" }, optional = true) Expression base,
-        @Param(name = "number", type = { "integer", "unsigned_long", "long", "double" }) Expression value
+        @Param(
+            name = "base",
+            type = { "integer", "unsigned_long", "long", "double" },
+            description = "Base of logarithm. If `null`, the function returns `null`. "
+                + "If not provided, this function returns the natural logarithm (base e) of a value.",
+            optional = true
+        ) Expression base,
+        @Param(
+            name = "number",
+            type = { "integer", "unsigned_long", "long", "double" },
+            description = "Numeric expression. If `null`, the function returns `null`."
+        ) Expression value
     ) {
         super(source, value != null ? Arrays.asList(base, value) : Arrays.asList(base));
         this.value = value != null ? value : base;

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

@@ -10,6 +10,7 @@ package org.elasticsearch.xpack.esql.expression.function.scalar.math;
 import org.elasticsearch.compute.ann.Evaluator;
 import org.elasticsearch.compute.operator.EvalOperator.ExpressionEvaluator;
 import org.elasticsearch.xpack.esql.EsqlIllegalArgumentException;
+import org.elasticsearch.xpack.esql.expression.function.Example;
 import org.elasticsearch.xpack.esql.expression.function.FunctionInfo;
 import org.elasticsearch.xpack.esql.expression.function.Param;
 import org.elasticsearch.xpack.esql.expression.function.scalar.UnaryScalarFunction;
@@ -28,8 +29,22 @@ import static org.elasticsearch.xpack.ql.expression.TypeResolutions.ParamOrdinal
 import static org.elasticsearch.xpack.ql.expression.TypeResolutions.isNumeric;
 
 public class Log10 extends UnaryScalarFunction {
-    @FunctionInfo(returnType = "double", description = "Returns the log base 10.")
-    public Log10(Source source, @Param(name = "number", type = { "double", "integer", "long", "unsigned_long" }) Expression n) {
+    @FunctionInfo(
+        returnType = "double",
+        description = "Returns the logarithm of a value to base 10. The input can "
+            + "be any numeric value, the return value is always a double.\n"
+            + "\n"
+            + "Logs of 0 and negative numbers return `null` as well as a warning.",
+        examples = @Example(file = "math", tag = "log10")
+    )
+    public Log10(
+        Source source,
+        @Param(
+            name = "number",
+            type = { "double", "integer", "long", "unsigned_long" },
+            description = "Numeric expression. If `null`, the function returns `null`."
+        ) Expression n
+    ) {
         super(source, n);
     }