[SPARK-58359][SQL] Require the arguments field in built-in function documentation

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/ApproxTopKExpressions.scala

@@ -42,6 +42,13 @@ import org.apache.spark.sql.types._
     _FUNC_(state, k) - Returns top k items with their frequency.
       `k` An optional INTEGER literal greater than 0. If k is not specified, it defaults to 5.
   """,
+  arguments = """
+    Arguments:
+      * state - The sketch state produced by `approx_top_k_accumulate` or
+          `approx_top_k_combine`.
+      * k - Optional. A constant INTEGER literal greater than 0 giving the number
+          of top items to return. If omitted, it defaults to 5.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(approx_top_k_accumulate(expr)) FROM VALUES (0), (0), (1), (1), (2), (3), (4), (4) AS tab(expr);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/CallMethodViaReflection.scala

@@ -51,6 +51,13 @@ import org.apache.spark.util.Utils
  */
 @ExpressionDescription(
   usage = "_FUNC_(class, method[, arg1[, arg2 ..]]) - Calls a method with reflection.",
+  arguments = """
+    Arguments:
+      * class - A literal string with the fully qualified name of the class.
+      * method - A literal string with the name of the static method to call.
+      * argN - Optional arguments passed to the method. Only primitive and string
+          types are supported, and each argument is matched to the method signature.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_('java.util.UUID', 'randomUUID');

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/Cast.scala

@@ -660,6 +660,11 @@ object Cast extends QueryErrorsBase {
 @ExpressionDescription(
   usage = "_FUNC_(expr AS type) - Casts the value `expr` to the target data type `type`." +
           " `expr` :: `type` alternative casting syntax is also supported.",
+  arguments = """
+    Arguments:
+      * expr - An expression whose value is converted to the target data type.
+      * type - The target data type to cast the value to.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_('10' as int);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/TryEval.scala

@@ -329,6 +329,12 @@ case class TryToBinary(
 @ExpressionDescription(
   usage = "_FUNC_(class, method[, arg1[, arg2 ..]]) - This is a special version of `reflect` that" +
     " performs the same operation, but returns a NULL value instead of raising an error if the invoke method thrown exception.",
+  arguments = """
+    Arguments:
+      * class - A string literal with the fully qualified name of the class.
+      * method - A string literal with the name of the static method to invoke.
+      * arg1, arg2, ... - Optional arguments passed to the invoked method.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_('java.util.UUID', 'randomUUID');

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/ApproxTopKAggregates.scala

@@ -798,6 +798,15 @@ object CombineInternal {
     _FUNC_(state, maxItemsTracked) - Combines multiple sketches into a single sketch.
       `maxItemsTracked` An optional positive INTEGER literal with upper limit of 1000000. If maxItemsTracked is specified, it will be set for the combined sketch. If maxItemsTracked is not specified, the input sketches must have the same maxItemsTracked value, otherwise an error will be thrown. The output sketch will use the same value from the input sketches.
   """,
+  arguments = """
+    Arguments:
+      * state - The sketch state to combine, as produced by approx_top_k_accumulate.
+          An expression that evaluates to the sketch state struct.
+      * maxItemsTracked - Optional. The maximum number of items to track in the combined
+          sketch, with an upper limit of 1000000. An expression that evaluates to an integer.
+          Must be a constant. If not specified, the input sketches must share the same
+          maxItemsTracked value, which is used for the output sketch.
+  """,
   examples = """
     Examples:
       > SELECT approx_top_k_estimate(_FUNC_(sketch, 10000), 5) FROM (SELECT approx_top_k_accumulate(expr) AS sketch FROM VALUES (0), (0), (1), (1) AS tab(expr) UNION ALL SELECT approx_top_k_accumulate(expr) AS sketch FROM VALUES (2), (3), (4), (4) AS tab(expr));

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/ApproximatePercentile.scala

@@ -66,6 +66,16 @@ import org.apache.spark.util.ArrayImplicits._
       In this case, returns the approximate percentile array of column `col` at the given
       percentage array.
   """,
+  arguments = """
+    Arguments:
+      * col - The numeric, ANSI interval or TIME column whose percentile is
+          computed.
+      * percentage - A value (or array of values) between 0.0 and 1.0 specifying
+          the percentile(s) to compute.
+      * accuracy - Optional. A positive numeric literal (default: 10000) that
+          controls approximation accuracy at the cost of memory. Higher values
+          yield better accuracy; `1.0/accuracy` is the relative error.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col, array(0.5, 0.4, 0.1), 100) FROM VALUES (0), (1), (2), (10) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/Count.scala

@@ -34,6 +34,11 @@ import org.apache.spark.sql.types._
 
     _FUNC_(DISTINCT expr[, expr...]) - Returns the number of rows for which the supplied expression(s) are unique and non-null.
   """,
+  arguments = """
+    Arguments:
+      * expr - One or more expressions. A row is counted only when all supplied
+          expressions are non-null. Use `*` to count all rows, including rows with nulls.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(*) FROM VALUES (NULL), (5), (5), (20) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/CountMinSketchAgg.scala

@@ -206,6 +206,13 @@ case class CountMinSketchAgg(
       `CountMinSketch` before usage. Count-min sketch is a probabilistic data structure used for
       cardinality estimation using sub-linear space.
   """,
+  arguments = """
+    Arguments:
+      * col - The column to build the count-min sketch from.
+      * eps - A double literal for the relative error of the sketch.
+      * confidence - A double literal for the confidence of the sketch.
+      * seed - An integer literal used as the random seed.
+  """,
   examples = """
     Examples:
       > SELECT hex(_FUNC_(col, 0.5d, 0.5d, 1)) FROM VALUES (1), (2), (1) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/HistogramNumeric.scala

@@ -51,6 +51,12 @@ import org.apache.spark.sql.util.NumericHistogram
       statistical computing packages. Note: the output type of the 'x' field in the return value is
       propagated from the input value consumed in the aggregate function.
     """,
+  arguments = """
+    Arguments:
+      * expr - A numeric, date, timestamp, or interval expression whose values are aggregated
+          into the histogram.
+      * nb - A foldable integer expression (at least 2) giving the number of histogram bins.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col, 5) FROM VALUES (0), (1), (2), (10) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/HyperLogLogPlusPlus.scala

@@ -50,6 +50,12 @@ import org.apache.spark.sql.types._
   usage = """
     _FUNC_(expr[, relativeSD]) - Returns the estimated cardinality by HyperLogLog++.
       `relativeSD` defines the maximum relative standard deviation allowed.""",
+  arguments = """
+    Arguments:
+      * expr - An expression of any type whose distinct values are counted.
+      * relativeSD - An optional double literal for the maximum relative standard
+          deviation allowed. Defaults to 0.05.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col1) FROM VALUES (1), (1), (2), (2), (3) tab(col1);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/Max.scala

@@ -27,6 +27,11 @@ import org.apache.spark.sql.types._
 
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the maximum value of `expr`.",
+  arguments = """
+    Arguments:
+      * expr - An expression of any orderable type whose maximum value across the group is
+          returned. NULL values are ignored.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (10), (50), (20) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/MaxMinByK.scala

@@ -240,6 +240,13 @@ case class MaxMinByK(
     maximum values of `y`, sorted in descending order by `y`.
     Returns NULL if there are no non-NULL ordering values.
   """,
+  arguments = """
+    Arguments:
+      * x - The value expression to return.
+      * y - The ordering expression whose maximum selects the value of `x`.
+      * k - An optional positive integer. When present, returns an array of the `k` values
+          of `x` associated with the largest values of `y`.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(x, y) FROM VALUES ('a', 10), ('b', 50), ('c', 20) AS tab(x, y);
@@ -275,6 +282,13 @@ object MaxByBuilder extends ExpressionBuilder {
     minimum values of `y`, sorted in ascending order by `y`.
     Returns NULL if there are no non-NULL ordering values.
   """,
+  arguments = """
+    Arguments:
+      * x - The value expression to return.
+      * y - The ordering expression whose minimum selects the value of `x`.
+      * k - An optional positive integer. When present, returns an array of the `k` values
+          of `x` associated with the smallest values of `y`.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(x, y) FROM VALUES ('a', 10), ('b', 50), ('c', 20) AS tab(x, y);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/Min.scala

@@ -27,6 +27,11 @@ import org.apache.spark.sql.types._
 
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the minimum value of `expr`.",
+  arguments = """
+    Arguments:
+      * expr - An expression of any orderable type whose minimum value across the group is
+          returned. NULL values are ignored.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (10), (-1), (20) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/collect.scala

@@ -104,6 +104,10 @@ abstract class Collect[T <: Growable[Any] with Iterable[Any]] extends TypedImper
  */
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Collects and returns a list of non-unique elements.",
+  arguments = """
+    Arguments:
+      * expr - An expression of any type whose values are collected into a list.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (1) AS tab(col);
@@ -181,6 +185,10 @@ case class CollectList(
  */
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Collects and returns a set of unique elements.",
+  arguments = """
+    Arguments:
+      * expr - An expression of any type whose values are collected into a set.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (1) AS tab(col);
@@ -336,6 +344,10 @@ case class CollectSet(
 @ExpressionDescription(
   usage =
     "_FUNC_(expr) - Collects and returns the distinct union of the elements of array `expr`.",
+  arguments = """
+    Arguments:
+      * expr - An array expression whose elements are collected into a set across rows.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (array(1, 2)), (array(2, 3)), (array(1)) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/datasketchesAggregates.scala

@@ -243,6 +243,14 @@ object HllSketchAgg {
     _FUNC_(expr, allowDifferentLgConfigK) - Returns the merged HllSketch's updatable binary representation.
       `allowDifferentLgConfigK` (optional) Allow sketches with different lgConfigK values
        to be unioned (defaults to false).""",
+  arguments = """
+    Arguments:
+      * expr - The binary representation of an HllSketch to merge.
+          An expression that evaluates to binary.
+      * allowDifferentLgConfigK - Optional. Whether to allow sketches with different
+          lgConfigK values to be unioned. An expression that evaluates to a boolean.
+          Defaults to false.
+  """,
   examples = """
     Examples:
       > SELECT hll_sketch_estimate(_FUNC_(sketch, true)) FROM (SELECT hll_sketch_agg(col) as sketch FROM VALUES (1) tab(col) UNION ALL SELECT hll_sketch_agg(col, 20) as sketch FROM VALUES (1) tab(col));

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/kllAggregates.scala

@@ -57,9 +57,10 @@ import org.apache.spark.sql.types.{AbstractDataType, BinaryType, ByteType, DataT
   arguments = """
     Arguments:
       * expr - The expression to aggregate into the KLL sketch.
-        An expression that evaluates to an integral.
-      * k - The parameter controlling the size and accuracy of the sketch.
-        An expression that evaluates to an integer. Must be a constant.
+          An expression that evaluates to an integral.
+      * k - Optional. The parameter controlling the size and accuracy of the sketch.
+          An expression that evaluates to an integer between 8 and 65535. Must be a
+          constant. Defaults to 200.
   """,
   examples = """
     Examples:
@@ -208,6 +209,14 @@ case class KllSketchAggBigint(
       The optional k parameter controls the size and accuracy of the sketch (default 200, range 8-65535).
       Larger k values provide more accurate quantile estimates but result in larger, slower sketches.
   """,
+  arguments = """
+    Arguments:
+      * expr - The expression to aggregate into the KLL sketch.
+          An expression that evaluates to a float.
+      * k - Optional. The parameter controlling the size and accuracy of the sketch.
+          An expression that evaluates to an integer between 8 and 65535. Must be a
+          constant. Defaults to 200.
+  """,
   examples = """
     Examples:
       > SELECT LENGTH(kll_sketch_to_string_float(_FUNC_(col))) > 0 FROM VALUES (CAST(1.0 AS FLOAT)), (CAST(2.0 AS FLOAT)), (CAST(3.0 AS FLOAT)), (CAST(4.0 AS FLOAT)), (CAST(5.0 AS FLOAT)) tab(col);
@@ -347,9 +356,10 @@ case class KllSketchAggFloat(
   arguments = """
     Arguments:
       * expr - The expression to aggregate into the KLL sketch.
-        An expression that evaluates to a float or double.
-      * k - The parameter controlling the size and accuracy of the sketch.
-        An expression that evaluates to an integer. Must be a constant.
+          An expression that evaluates to a float or double.
+      * k - Optional. The parameter controlling the size and accuracy of the sketch.
+          An expression that evaluates to an integer between 8 and 65535. Must be a
+          constant. Defaults to 200.
   """,
   examples = """
     Examples:
@@ -493,6 +503,14 @@ case class KllSketchAggDouble(
       The optional k parameter controls the size and accuracy of the merged sketch (range 8-65535).
       If k is not specified, the merged sketch adopts the k value from the first input sketch.
   """,
+  arguments = """
+    Arguments:
+      * expr - The expression to merge into the KLL sketch.
+          An expression that evaluates to a binary KLL sketch representation.
+      * k - Optional. The parameter controlling the size and accuracy of the merged
+          sketch. An expression that evaluates to an integer between 8 and 65535. Must be
+          a constant. Defaults to the k value of the first input sketch.
+  """,
   examples = """
     Examples:
       > SELECT kll_sketch_get_n_bigint(_FUNC_(sketch)) FROM (SELECT kll_sketch_agg_bigint(col) as sketch FROM VALUES (1), (2), (3) tab(col) UNION ALL SELECT kll_sketch_agg_bigint(col) as sketch FROM VALUES (4), (5), (6) tab(col)) t;
@@ -566,6 +584,14 @@ case class KllMergeAggBigint(
       The optional k parameter controls the size and accuracy of the merged sketch (range 8-65535).
       If k is not specified, the merged sketch adopts the k value from the first input sketch.
   """,
+  arguments = """
+    Arguments:
+      * expr - The expression to merge into the KLL sketch.
+          An expression that evaluates to a binary KLL sketch representation.
+      * k - Optional. The parameter controlling the size and accuracy of the merged
+          sketch. An expression that evaluates to an integer between 8 and 65535. Must be
+          a constant. Defaults to the k value of the first input sketch.
+  """,
   examples = """
     Examples:
       > SELECT kll_sketch_get_n_float(_FUNC_(sketch)) FROM (SELECT kll_sketch_agg_float(col) as sketch FROM VALUES (CAST(1.0 AS FLOAT)), (CAST(2.0 AS FLOAT)), (CAST(3.0 AS FLOAT)) tab(col) UNION ALL SELECT kll_sketch_agg_float(col) as sketch FROM VALUES (CAST(4.0 AS FLOAT)), (CAST(5.0 AS FLOAT)), (CAST(6.0 AS FLOAT)) tab(col)) t;
@@ -639,6 +665,14 @@ case class KllMergeAggFloat(
       The optional k parameter controls the size and accuracy of the merged sketch (range 8-65535).
       If k is not specified, the merged sketch adopts the k value from the first input sketch.
   """,
+  arguments = """
+    Arguments:
+      * expr - The expression to merge into the KLL sketch.
+          An expression that evaluates to a binary KLL sketch representation.
+      * k - Optional. The parameter controlling the size and accuracy of the merged
+          sketch. An expression that evaluates to an integer between 8 and 65535. Must be
+          a constant. Defaults to the k value of the first input sketch.
+  """,
   examples = """
     Examples:
       > SELECT kll_sketch_get_n_double(_FUNC_(sketch)) FROM (SELECT kll_sketch_agg_double(col) as sketch FROM VALUES (CAST(1.0 AS DOUBLE)), (CAST(2.0 AS DOUBLE)), (CAST(3.0 AS DOUBLE)) tab(col) UNION ALL SELECT kll_sketch_agg_double(col) as sketch FROM VALUES (CAST(4.0 AS DOUBLE)), (CAST(5.0 AS DOUBLE)), (CAST(6.0 AS DOUBLE)) tab(col)) t;

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/percentiles.scala

@@ -271,6 +271,15 @@ abstract class PercentileBase
       positive integral
 
       """,
+  arguments = """
+    Arguments:
+      * col - The column to compute the percentile of.
+          An expression that evaluates to a numeric, ANSI interval, or time.
+      * percentage - The percentile(s) to compute, each between 0.0 and 1.0. Either a
+          single numeric value or an array of numeric values. Must be foldable.
+      * frequency - Optional. The number of times each value should be counted.
+          An expression that evaluates to a positive integral value. Defaults to 1.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col, 0.3) FROM VALUES (0), (10) AS tab(col);
@@ -493,6 +502,12 @@ case class PercentileDisc(
   usage = "_FUNC_(percentage) WITHIN GROUP (ORDER BY col) - Return a percentile value based on " +
     "a continuous distribution of numeric, ANSI interval or TIME column `col` at the given " +
     "`percentage` (specified in ORDER BY clause).",
+  arguments = """
+    Arguments:
+      * percentage - The percentile to compute, between 0.0 and 1.0. Must be foldable.
+      * col - The column to compute the percentile of, specified in the ORDER BY clause.
+          An expression that evaluates to a numeric, ANSI interval, or time.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(0.25) WITHIN GROUP (ORDER BY col) FROM VALUES (0), (10) AS tab(col);
@@ -519,6 +534,12 @@ object PercentileContBuilder extends ExpressionBuilder {
   usage = "_FUNC_(percentage) WITHIN GROUP (ORDER BY col) - Return a percentile value based on " +
     "a discrete distribution of numeric, ANSI interval or TIME column `col` at the given " +
     "`percentage` (specified in ORDER BY clause).",
+  arguments = """
+    Arguments:
+      * percentage - The percentile to compute, between 0.0 and 1.0. Must be foldable.
+      * col - The column to compute the percentile of, specified in the ORDER BY clause.
+          An expression that evaluates to a numeric, ANSI interval, or time.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(0.25) WITHIN GROUP (ORDER BY col) FROM VALUES (0), (10) AS tab(col);

sql/catalyst/src/main/scala/org/apache/spark/sql/catalyst/expressions/aggregate/thetasketchesAggregates.scala

@@ -323,6 +323,13 @@ case class ThetaSketchAgg(
     _FUNC_(expr, lgNomEntries) - Returns the ThetaSketch's Compact binary representation.
       `lgNomEntries` (optional) the log-base-2 of Nominal Entries, with Nominal Entries deciding
       the number buckets or slots for the ThetaSketch.""",
+  arguments = """
+    Arguments:
+      * expr - A binary expression of Compact ThetaSketch representations to union.
+      * lgNomEntries - An optional integer expression, the log-base-2 of nominal entries which
+          sets the number of buckets for the resulting ThetaSketch. When omitted, it defaults to
+          the default log nominal entries.
+  """,
   examples = """
     Examples:
       > SELECT theta_sketch_estimate(_FUNC_(sketch)) FROM (SELECT theta_sketch_agg(col) as sketch FROM VALUES (1) tab(col) UNION ALL SELECT theta_sketch_agg(col, 20) as sketch FROM VALUES (1) tab(col));
@@ -507,6 +514,10 @@ case class ThetaUnionAgg(
   usage = """
     _FUNC_(expr) - Returns the ThetaSketch's Compact binary representation
       by intersecting all the Theta sketches in the input column.""",
+  arguments = """
+    Arguments:
+      * expr - A binary expression of Compact ThetaSketch representations to intersect.
+  """,
   examples = """
     Examples:
       > SELECT theta_sketch_estimate(_FUNC_(sketch)) FROM (SELECT theta_sketch_agg(col) as sketch FROM VALUES (1) tab(col) UNION ALL SELECT theta_sketch_agg(col, 20) as sketch FROM VALUES (1) tab(col));