Review feedback

abdonpijpelink · Jan 25, 2024 · 72e1427 · 72e1427
1 parent 3750c87
commit 72e1427
Show file tree

Hide file tree

Showing 30 changed files with 56 additions and 66 deletions.
diff --git a/docs/reference/esql/functions/asin.asciidoc b/docs/reference/esql/functions/asin.asciidoc
@@ -14,9 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the
-https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arcsine]
-of the input numeric expression as an angle, expressed in radians.
+Returns the {wikipedia}/Inverse_trigonometric_functions[arcsine] of the input
+numeric expression as an angle, expressed in radians.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/atan.asciidoc b/docs/reference/esql/functions/atan.asciidoc
@@ -14,9 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the
-https://en.wikipedia.org/wiki/Inverse_trigonometric_functions[arctangent] of the
-input numeric expression as an angle, expressed in radians.
+Returns the {wikipedia}/Inverse_trigonometric_functions[arctangent] of the input
+numeric expression as an angle, expressed in radians.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/atan2.asciidoc b/docs/reference/esql/functions/atan2.asciidoc
@@ -17,9 +17,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-The https://en.wikipedia.org/wiki/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.
+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*
 

diff --git a/docs/reference/esql/functions/cos.asciidoc b/docs/reference/esql/functions/cos.asciidoc
@@ -14,8 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the https://en.wikipedia.org/wiki/Sine_and_cosine[cosine] of `n`. Input
-expected in radians.
+Returns the {wikipedia}/Sine_and_cosine[cosine] of `n`. Input expected in
+radians.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/cosh.asciidoc b/docs/reference/esql/functions/cosh.asciidoc
@@ -12,14 +12,13 @@ image::esql/functions/signature/cosh.svg[Embedded,opts=inline]
 `n`::
 Numeric expression. If `null`, the function returns `null`.
 
-*Supported types*
+*Description*
 
-include::types/cosh.asciidoc[]
+Returns the {wikipedia}/Hyperbolic_functions[hyperbolic cosine].
 
-*Description*
+*Supported types*
 
-Returns the https://en.wikipedia.org/wiki/Hyperbolic_functions[hyperbolic
-cosine].
+include::types/cosh.asciidoc[]
 
 *Example*
 

diff --git a/docs/reference/esql/functions/median-absolute-deviation.asciidoc b/docs/reference/esql/functions/median-absolute-deviation.asciidoc
@@ -23,7 +23,7 @@ than standard deviation.
 
 It is calculated as the median of each data point's deviation from the median of
 the entire sample. That is, for a random variable `X`, the median absolute
-deviation is `median(|median(X) - Xi|)`.
+deviation is `median(|median(X) - X|)`.
 
 NOTE: Like <<esql-agg-percentile>>, `MEDIAN_ABSOLUTE_DEVIATION` is
       <<esql-agg-percentile-approximate,usually approximate>>.

diff --git a/docs/reference/esql/functions/mv_first.asciidoc b/docs/reference/esql/functions/mv_first.asciidoc
@@ -22,8 +22,7 @@ The order that <<esql-multivalued-fields, multivalued fields>> are read from
 underlying storage is not guaranteed. It is *frequently* ascending, but don't
 rely on that. If you need the minimum value use <<esql-mv_min>> instead of
 `MV_FIRST`. `MV_MIN` has optimizations for sorted values so there isn't a
-performance benefit to `MV_FIRST`. `MV_FIRST` is mostly useful with functions
-that create multivalued columns like `SPLIT`.
+performance benefit to `MV_FIRST`.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/mv_last.asciidoc b/docs/reference/esql/functions/mv_last.asciidoc
@@ -14,14 +14,15 @@ Multivalue expression.
 
 *Description*
 
-Converts a multivalue expression into a single valued column containing the last value. This is most
-useful when reading from a function that emits multivalued fields in a known order like <<esql-split>>:
-
-The order that <<esql-multivalued-fields, multivalued fields>> are read from underlying storage is not
-guaranteed. It is *frequently* ascending, but don't rely on that. If you need the maximum field value
-use <<esql-mv_max>> instead of `MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't
-a performance benefit to `MV_LAST`. `MV_LAST` is mostly useful with functions that create multivalued
-columns like `SPLIT`.
+Converts a multivalue expression into a single valued column containing the last
+value. This is most useful when reading from a function that emits multivalued
+columns in a known order like <<esql-split>>.
+
+The order that <<esql-multivalued-fields, multivalued fields>> are read from
+underlying storage is not guaranteed. It is *frequently* ascending, but don't
+rely on that. If you need the maximum value use <<esql-mv_max>> instead of
+`MV_LAST`. `MV_MAX` has optimizations for sorted values so there isn't a
+performance benefit to `MV_LAST`.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/mv_max.asciidoc b/docs/reference/esql/functions/mv_max.asciidoc
@@ -14,8 +14,8 @@ Multivalue expression.
 
 *Description*
 
-Converts a multivalued column into a single valued column containing the maximum
-value.
+Converts a multivalued expression into a single valued column containing the
+maximum value.
 
 *Supported types*
 
@@ -33,7 +33,7 @@ include::{esql-specs}/math.csv-spec[tag=mv_max-result]
 |===
 
 It can be used by any column type, including `keyword` columns. In that case
-picks the last string, comparing their utf-8 representation byte by byte:
+it picks the last string, comparing their utf-8 representation byte by byte:
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/functions/mv_min.asciidoc b/docs/reference/esql/functions/mv_min.asciidoc
@@ -33,7 +33,7 @@ include::{esql-specs}/math.csv-spec[tag=mv_min-result]
 |===
 
 It can be used by any column type, including `keyword` columns. In that case,
-picks the first string, comparing their utf-8 representation byte by byte:
+it picks the first string, comparing their utf-8 representation byte by byte:
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/functions/percentile.asciidoc b/docs/reference/esql/functions/percentile.asciidoc
@@ -15,7 +15,7 @@ PERCENTILE(column, percentile)
 Column to convert from multiple values to single value.
 
 `percentile`::
-A numeric expression.
+A constant numeric expression.
 
 *Description*
 

diff --git a/docs/reference/esql/functions/pow.asciidoc b/docs/reference/esql/functions/pow.asciidoc
@@ -17,10 +17,9 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-Returns the value of a base (first argument) raised to the power of an exponent
-(second argument). 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.
+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.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/replace.asciidoc b/docs/reference/esql/functions/replace.asciidoc
@@ -20,8 +20,8 @@ Replacement string.
 
 *Description*
 
-The function substitutes in the string (1st argument) any match of the regular
-expression (2nd argument) with the replacement string (3rd argument).
+The function substitutes in the string `str` any match of the regular expression
+`regex` with the replacement string `newStr`.
 
 If any of the arguments is `null`, the result is `null`.
 

diff --git a/docs/reference/esql/functions/sin.asciidoc b/docs/reference/esql/functions/sin.asciidoc
@@ -14,8 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Sine] trigonometric function.
-Input expected in radians.
+{wikipedia}/Sine_and_cosine[Sine] trigonometric function. Input expected in
+radians.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/sinh.asciidoc b/docs/reference/esql/functions/sinh.asciidoc
@@ -14,7 +14,7 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-https://en.wikipedia.org/wiki/Hyperbolic_functions[Sine] hyperbolic function.
+{wikipedia}/Hyperbolic_functions[Sine] hyperbolic function.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/substring.asciidoc b/docs/reference/esql/functions/substring.asciidoc
@@ -16,7 +16,8 @@ String expression. If `null`, the function returns `null`.
 Start position.
 
 `length`::
-Length.
+Length of the substring from the start position. Optional; if omitted, all
+positions after `start` are returned.
 
 *Description*
 

diff --git a/docs/reference/esql/functions/tan.asciidoc b/docs/reference/esql/functions/tan.asciidoc
@@ -14,8 +14,8 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-https://en.wikipedia.org/wiki/Sine_and_cosine[Tangent] trigonometric function.
-Input expected in radians.
+{wikipedia}/Sine_and_cosine[Tangent] trigonometric function. Input expected in
+radians.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/tanh.asciidoc b/docs/reference/esql/functions/tanh.asciidoc
@@ -14,7 +14,7 @@ Numeric expression. If `null`, the function returns `null`.
 
 *Description*
 
-https://en.wikipedia.org/wiki/Hyperbolic_functions[Tangent] hyperbolic function.
+{wikipedia}/Hyperbolic_functions[Tangent] hyperbolic function.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_cartesianpoint.asciidoc b/docs/reference/esql/functions/to_cartesianpoint.asciidoc
@@ -19,8 +19,7 @@ Input value. The input can be a single- or multi-valued column or an expression.
 Converts an input value to a `point` value.
 
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT
-Point] format.
+{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_cartesianshape.asciidoc b/docs/reference/esql/functions/to_cartesianshape.asciidoc
@@ -20,7 +20,7 @@ The input type must be a string or a `cartesian_shape`.
 Converts an input value to a `cartesian_shape` value.
 
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT] format.
+{wikipedia}/Well-known_text_representation_of_geometry[WKT] format.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_datetime.asciidoc b/docs/reference/esql/functions/to_datetime.asciidoc
@@ -54,8 +54,7 @@ A following header will contain the failure reason and the offending value:
 `"java.lang.IllegalArgumentException: failed to parse date field [1964-06-02 00:00:00] with format [yyyy-MM-dd'T'HH:mm:ss.SSS'Z']"`
 
 If the input parameter is of a numeric type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch].
-For example:
+milliseconds since the {wikipedia}/Unix_time[Unix epoch]. For example:
 
 [source.merge.styled,esql]
 ----

diff --git a/docs/reference/esql/functions/to_degrees.asciidoc b/docs/reference/esql/functions/to_degrees.asciidoc
@@ -16,8 +16,8 @@ Input value. The input can be a single- or multi-valued column or an expression.
 
 *Description*
 
-Converts a number in https://en.wikipedia.org/wiki/Radian[radians] to
-https://en.wikipedia.org/wiki/Degree_(angle)[degrees].
+Converts a number in {wikipedia}/Radian[radians] to
+{wikipedia}/Degree_(angle)[degrees].
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_double.asciidoc b/docs/reference/esql/functions/to_double.asciidoc
@@ -23,8 +23,7 @@ Input value. The input can be a single- or multi-valued column or an expression.
 Converts an input value to a double value.
 
 If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to double.
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to double.
 
 Boolean *true* will be converted to double *1.0*, *false* to *0.0*.
 

diff --git a/docs/reference/esql/functions/to_geopoint.asciidoc b/docs/reference/esql/functions/to_geopoint.asciidoc
@@ -24,7 +24,7 @@ Converts an input value to a `geo_point` value.
 include::types/to_geopoint.asciidoc[]
 
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT Point] format.
+{wikipedia}/Well-known_text_representation_of_geometry[WKT Point] format.
 
 *Example*
 

diff --git a/docs/reference/esql/functions/to_geoshape.asciidoc b/docs/reference/esql/functions/to_geoshape.asciidoc
@@ -20,8 +20,7 @@ The input type must be a string or a `geo_shape`.
 Converts an input value to a `geo_shape` value.
 
 A string will only be successfully converted if it respects the
-https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry[WKT] format:
-
+{wikipedia}/Well-known_text_representation_of_geometry[WKT] format.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_integer.asciidoc b/docs/reference/esql/functions/to_integer.asciidoc
@@ -23,8 +23,7 @@ Input value. The input can be a single- or multi-valued column or an expression.
 Converts an input value to an integer  value.
 
 If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to integer.
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to integer.
 
 Boolean *true* will be converted to integer *1*, *false* to *0*.
 

diff --git a/docs/reference/esql/functions/to_long.asciidoc b/docs/reference/esql/functions/to_long.asciidoc
@@ -19,8 +19,7 @@ Input value. The input can be a single- or multi-valued column or an expression.
 Converts an input value to a long value.
 
 If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to long.
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to long.
 
 Boolean *true* will be converted to long *1*, *false* to *0*.
 

diff --git a/docs/reference/esql/functions/to_radians.asciidoc b/docs/reference/esql/functions/to_radians.asciidoc
@@ -16,8 +16,8 @@ Input value. The input can be a single- or multi-valued column or an expression.
 
 *Description*
 
-Converts a number in https://en.wikipedia.org/wiki/Degree_(angle)[degrees] to
-https://en.wikipedia.org/wiki/Radian[radians].
+Converts a number in {wikipedia}/Degree_(angle)[degrees] to
+{wikipedia}/Radian[radians].
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_string.asciidoc b/docs/reference/esql/functions/to_string.asciidoc
@@ -16,7 +16,7 @@ Input value. The input can be a single- or multi-valued column or an expression.
 
 *Description*
 
-Converts a field into a string.
+Converts an input value into a string.
 
 *Supported types*
 

diff --git a/docs/reference/esql/functions/to_unsigned_long.asciidoc b/docs/reference/esql/functions/to_unsigned_long.asciidoc
@@ -27,8 +27,8 @@ Converts an input value to an unsigned long value.
 The input type must be of a boolean, date, string or numeric type.
 
 If the input parameter is of a date type, its value will be interpreted as
-milliseconds since the https://en.wikipedia.org/wiki/Unix_time[Unix epoch],
-converted to unsigned long.
+milliseconds since the {wikipedia}/Unix_time[Unix epoch], converted to unsigned
+long.
 
 Boolean *true* will be converted to unsigned long *1*, *false* to *0*.