[SPARK-57999][SQL][PYTHON][DOCS] Document accepted input and return types for built-in functions

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

@@ -30,7 +30,11 @@ import org.apache.spark.sql.internal.SQLConf
   arguments = """
     Arguments:
       * input - An expression that is being compared with lower and upper bound.
+        An expression that evaluates to a boolean, numeric, string, binary, date, timestamp, time,
+        interval, array, or struct.
       * lower - Lower bound of the between check.
+        An expression that evaluates to a boolean, numeric, string, binary, date, timestamp, time,
+        interval, array, or struct.
       * upper - Upper bound of the between check.
   """,
   since = "1.0.0",

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

@@ -58,6 +58,13 @@ case class TryEval(child: Expression) extends UnaryExpression {
 @ExpressionDescription(
   usage = "_FUNC_(expr1, expr2) - Returns the sum of `expr1`and `expr2` and the result is null on overflow. " +
     "The acceptable input types are the same with the `+` operator.",
+  arguments = """
+    Arguments:
+      * expr1 - The first addend.
+        An expression that evaluates to a numeric, interval, date, timestamp, or time.
+      * expr2 - The second addend.
+        An expression that evaluates to a numeric, interval, date, timestamp, or time.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(1, 2);
@@ -102,6 +109,13 @@ case class TryAdd(left: Expression, right: Expression, replacement: Expression)
 @ExpressionDescription(
   usage = "_FUNC_(dividend, divisor) - Returns `dividend`/`divisor`. It always performs floating point division. Its result is always null if `expr2` is 0. " +
     "`dividend` must be a numeric or an interval. `divisor` must be a numeric.",
+  arguments = """
+    Arguments:
+      * dividend - The expression to be divided.
+        An expression that evaluates to a numeric or interval.
+      * divisor - The expression to divide by.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(3, 2);
@@ -141,6 +155,13 @@ case class TryDivide(left: Expression, right: Expression, replacement: Expressio
 @ExpressionDescription(
   usage = "_FUNC_(dividend, divisor) - Returns the remainder after `expr1`/`expr2`. " +
     "`dividend` must be a numeric. `divisor` must be a numeric.",
+  arguments = """
+    Arguments:
+      * dividend - The expression to be divided.
+        An expression that evaluates to a numeric.
+      * divisor - The expression to divide by.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(3, 2);
@@ -177,6 +198,13 @@ case class TryMod(left: Expression, right: Expression, replacement: Expression)
 @ExpressionDescription(
   usage = "_FUNC_(expr1, expr2) - Returns `expr1`-`expr2` and the result is null on overflow. " +
     "The acceptable input types are the same with the `-` operator.",
+  arguments = """
+    Arguments:
+      * expr1 - The minuend to subtract from.
+        An expression that evaluates to a numeric, interval, date, timestamp, or time.
+      * expr2 - The subtrahend to subtract.
+        An expression that evaluates to a numeric, interval, date, timestamp, or time.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(2, 1);
@@ -219,6 +247,13 @@ case class TrySubtract(left: Expression, right: Expression, replacement: Express
 @ExpressionDescription(
   usage = "_FUNC_(expr1, expr2) - Returns `expr1`*`expr2` and the result is null on overflow. " +
     "The acceptable input types are the same with the `*` operator.",
+  arguments = """
+    Arguments:
+      * expr1 - The first factor.
+        An expression that evaluates to a numeric or interval.
+      * expr2 - The second factor.
+        An expression that evaluates to a numeric or interval.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(2, 3);
@@ -251,6 +286,13 @@ case class TryMultiply(left: Expression, right: Expression, replacement: Express
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(str[, fmt]) - This is a special version of `to_binary` that performs the same operation, but returns a NULL value instead of raising an error if the conversion cannot be performed.",
+  arguments = """
+    Arguments:
+      * str - The string to convert to a binary value.
+        An expression that evaluates to a string.
+      * fmt - The format of the input string.
+        An expression that evaluates to a string. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_('abc', 'utf-8');

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

@@ -34,6 +34,13 @@ import org.apache.spark.sql.types._
   usage = """
     _FUNC_(expr[, isIgnoreNull]) - Returns some value of `expr` for a group of rows.
       If `isIgnoreNull` is true, returns only non-null values.""",
+  arguments = """
+    Arguments:
+      * expr - The expression to return some value of.
+        An expression of any type.
+      * isIgnoreNull - Whether to return only non-null values.
+        An expression that evaluates to a boolean. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (10), (5), (20) AS tab(col);

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

@@ -59,6 +59,15 @@ import org.apache.spark.unsafe.types.UTF8String
       `k` An optional INTEGER literal greater than 0. If k is not specified, it defaults to 5.
       `maxItemsTracked` An optional INTEGER literal greater than or equal to k and has upper limit of 1000000. If maxItemsTracked is not specified, it defaults to 10000.
   """,
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the top k most frequent items of.
+        An expression that evaluates to a boolean, numeric, date, timestamp, or string.
+      * k - The number of top items to return.
+        An expression that evaluates to an integer. Must be a constant.
+      * maxItemsTracked - The maximum number of items to track in the sketch.
+        An expression that evaluates to an integer. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(expr) FROM VALUES (0), (0), (1), (1), (2), (3), (4), (4) AS tab(expr);
@@ -488,6 +497,13 @@ object ApproxTopKAggregateBuffer {
     _FUNC_(expr, maxItemsTracked) - Accumulates items into a sketch.
       `maxItemsTracked` An optional positive INTEGER literal with upper limit of 1000000. If maxItemsTracked is not specified, it defaults to 10000.
   """,
+  arguments = """
+    Arguments:
+      * expr - The expression whose values are accumulated into the sketch.
+        An expression that evaluates to a boolean, numeric, date, timestamp, or string.
+      * maxItemsTracked - The maximum number of items to track in the sketch.
+        An expression that evaluates to an integer. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT approx_top_k_estimate(_FUNC_(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/aggregate/Average.scala

@@ -30,6 +30,11 @@ import org.apache.spark.sql.types._
 
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the mean calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to average over the group.
+        An expression that evaluates to a numeric or interval.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (3) AS tab(col);
@@ -145,6 +150,11 @@ case class Average(
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the mean calculated from values of a group and the result is null on overflow.",
+  arguments = """
+    Arguments:
+      * expr - The expression to average over the group.
+        An expression that evaluates to a numeric or interval.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (3) AS tab(col);

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

@@ -147,6 +147,11 @@ abstract class CentralMomentAgg(child: Expression, nullOnDivideByZero: Boolean)
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the population standard deviation calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the population standard deviation of.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (3) AS tab(col);
@@ -178,6 +183,11 @@ case class StddevPop(
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the sample standard deviation calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the sample standard deviation of.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (3) AS tab(col);
@@ -210,6 +220,11 @@ case class StddevSamp(
 // Compute the population variance of a column
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the population variance calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the population variance of.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (3) AS tab(col);
@@ -239,6 +254,11 @@ case class VariancePop(
 // Compute the sample variance of a column
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the sample variance calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the sample variance of.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (1), (2), (3) AS tab(col);
@@ -281,6 +301,11 @@ case class RegrReplacement(child: Expression)
 
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the skewness value calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the skewness of.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (-10), (-20), (100), (1000) AS tab(col);
@@ -312,6 +337,11 @@ case class Skewness(
 
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the kurtosis value calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to compute the kurtosis of.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (-10), (-20), (100), (1000) AS tab(col);

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

@@ -105,6 +105,13 @@ abstract class PearsonCorrelation(x: Expression, y: Expression, nullOnDivideByZe
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(expr1, expr2) - Returns Pearson coefficient of correlation between a set of number pairs.",
+  arguments = """
+    Arguments:
+      * expr1 - The first variable of the number pairs.
+        An expression that evaluates to a numeric.
+      * expr2 - The second variable of the number pairs.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(c1, c2) FROM VALUES (3, 2), (3, 3), (6, 4) as tab(c1, c2);

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

@@ -25,6 +25,11 @@ import org.apache.spark.sql.types.{AbstractDataType, BooleanType}
   usage = """
     _FUNC_(expr) - Returns the number of `TRUE` values for the expression.
   """,
+  arguments = """
+    Arguments:
+      * expr - The boolean expression whose TRUE values are counted.
+        An expression that evaluates to a boolean.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col % 2 = 0) FROM VALUES (NULL), (0), (1), (2), (3) AS tab(col);

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

@@ -90,6 +90,13 @@ abstract class Covariance(val left: Expression, val right: Expression, nullOnDiv
 
 @ExpressionDescription(
   usage = "_FUNC_(expr1, expr2) - Returns the population covariance of a set of number pairs.",
+  arguments = """
+    Arguments:
+      * expr1 - The first variable of the number pairs.
+        An expression that evaluates to a numeric.
+      * expr2 - The second variable of the number pairs.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(c1, c2) FROM VALUES (1,1), (2,2), (3,3) AS tab(c1, c2);
@@ -119,6 +126,13 @@ case class CovPopulation(
 
 @ExpressionDescription(
   usage = "_FUNC_(expr1, expr2) - Returns the sample covariance of a set of number pairs.",
+  arguments = """
+    Arguments:
+      * expr1 - The first variable of the number pairs.
+        An expression that evaluates to a numeric.
+      * expr2 - The second variable of the number pairs.
+        An expression that evaluates to a numeric.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(c1, c2) FROM VALUES (1,1), (2,2), (3,3) AS tab(c1, c2);

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

@@ -36,6 +36,13 @@ import org.apache.spark.sql.types._
   usage = """
     _FUNC_(expr[, isIgnoreNull]) - Returns the first value of `expr` for a group of rows.
       If `isIgnoreNull` is true, returns only non-null values.""",
+  arguments = """
+    Arguments:
+      * expr - The expression to return the first value of.
+        An expression of any type.
+      * isIgnoreNull - Whether to ignore null values and return only the first non-null value.
+        An expression that evaluates to a boolean. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (10), (5), (20) AS tab(col);

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

@@ -35,6 +35,13 @@ import org.apache.spark.sql.types._
   usage = """
     _FUNC_(expr[, isIgnoreNull]) - Returns the last value of `expr` for a group of rows.
       If `isIgnoreNull` is true, returns only non-null values""",
+  arguments = """
+    Arguments:
+      * expr - The expression to return the last value of.
+        An expression of any type.
+      * isIgnoreNull - Whether to ignore null values and return only the last non-null value.
+        An expression that evaluates to a boolean. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (10), (5), (20) AS tab(col);

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

@@ -30,6 +30,11 @@ import org.apache.spark.sql.types.{AbstractDataType, AnyDataType, DataType}
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(expr) - this function is used and can only be used to calculate a measure defined in a metric view.",
+  arguments = """
+    Arguments:
+      * expr - The measure defined in a metric view to calculate.
+        An expression of any type.
+  """,
   examples = """
     Examples:
       > SELECT dimension_col, _FUNC_(measure_col)

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

@@ -233,6 +233,14 @@ case class Mode(
     _FUNC_() WITHIN GROUP (ORDER BY col) - Returns the most frequent value for the values within `col` (specified in ORDER BY clause). NULL values are ignored.
       If all the values are NULL, or there are 0 rows, returns NULL. When multiple values have the same greatest frequency only one value will be returned.
       The value will be chosen based on sort direction. Return the smallest value if sort direction is asc or the largest value if sort direction is desc from multiple values with the same frequency.""",
+  arguments = """
+    Arguments:
+      * col - The column to compute the most frequent value of.
+        An expression of any type.
+      * deterministic - Whether to return a deterministic result when there are multiple most
+          frequent values.
+        An expression that evaluates to a boolean. Must be a constant.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (0), (10), (10) AS tab(col);

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

@@ -30,6 +30,11 @@ import org.apache.spark.sql.types._
 
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the sum calculated from values of a group.",
+  arguments = """
+    Arguments:
+      * expr - The expression to sum over the group.
+        An expression that evaluates to a numeric or interval.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (5), (10), (15) AS tab(col);
@@ -201,6 +206,11 @@ case class Sum(
 // scalastyle:off line.size.limit
 @ExpressionDescription(
   usage = "_FUNC_(expr) - Returns the sum calculated from values of a group and the result is null on overflow.",
+  arguments = """
+    Arguments:
+      * expr - The expression to sum over the group.
+        An expression that evaluates to a numeric or interval.
+  """,
   examples = """
     Examples:
       > SELECT _FUNC_(col) FROM VALUES (5), (10), (15) AS tab(col);