Rename TypeSignature::NullAry --> TypeSignature::Nullary and impr…

…ove comments

datafusion/expr-common/src/signature.rs

@@ -74,6 +74,8 @@ pub enum Volatility {
 /// adds a cast such as `cos(CAST int_column AS DOUBLE)` during planning.
 ///
 /// # Data Types
+///
+/// ## Timestamps
 /// Types to match are represented using Arrow's [`DataType`].  [`DataType::Timestamp`] has an optional variable
 /// timezone specification. To specify a function can handle a timestamp with *ANY* timezone, use
 /// the [`TIMEZONE_WILDCARD`]. For example:
@@ -93,6 +95,8 @@ pub enum Volatility {
 pub enum TypeSignature {
     /// One or more arguments of a common type out of a list of valid types.
     ///
+    /// For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
+    ///
     /// # Examples
     /// A function such as `concat` is `Variadic(vec![DataType::Utf8, DataType::LargeUtf8])`
     Variadic(Vec<DataType>),
@@ -102,51 +106,75 @@ pub enum TypeSignature {
     UserDefined,
     /// One or more arguments with arbitrary types
     VariadicAny,
-    /// Fixed number of arguments of an arbitrary but equal type out of a list of valid types.
+    /// One or more arguments of an arbitrary but equal type out of a list of valid types.
     ///
     /// # Examples
     /// 1. A function of one argument of f64 is `Uniform(1, vec![DataType::Float64])`
     /// 2. A function of one argument of f64 or f32 is `Uniform(1, vec![DataType::Float32, DataType::Float64])`
     Uniform(usize, Vec<DataType>),
-    /// Exact number of arguments of an exact type
+    /// One or more arguments with exactly the specified types in order.
+    ///
+    /// For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
     Exact(Vec<DataType>),
-    /// The number of arguments that can be coerced to in order
+    /// One or more arguments belonging to the [`TypeSignatureClass`], in order.
+    ///
     /// For example, `Coercible(vec![logical_float64()])` accepts
     /// arguments like `vec![DataType::Int32]` or `vec![DataType::Float32]`
-    /// since i32 and f32 can be casted to f64
+    /// since i32 and f32 can be cast to f64
+    ///
+    /// For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
     Coercible(Vec<TypeSignatureClass>),
-    /// The arguments will be coerced to a single type based on the comparison rules.
-    /// For example, i32 and i64 has coerced type Int64.
+    /// One or more arguments that can be "compared"
+    ///
+    /// Each argument will be coerced to a single type based on comparison rules.
+    /// For example a function called with `i32` and `i64` has coerced type `Int64` so
+    /// each argument will be coerced to `Int64` before the function is invoked.
     ///
     /// Note:
-    /// - If compares with numeric and string, numeric is preferred for numeric string cases. For example, nullif('2', 1) has coerced types Int64.
+    /// - If compares with numeric and string, numeric is preferred for numeric string cases. For example, `nullif('2', 1)` has coerced types `Int64`.
     /// - If the result is Null, it will be coerced to String (Utf8View).
+    /// - See [`comparison_coercion`] for more details.
+    /// - For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
     ///
-    /// See `comparison_coercion_numeric` for more details.
+    /// [`comparison_coercion`]: crate::type_coercion::binary::comparison_coercion
     Comparable(usize),
-    /// Fixed number of arguments of arbitrary types, number should be larger than 0
+    /// One or more arguments of arbitrary types.
+    ///
+    /// For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
     Any(usize),
-    /// Matches exactly one of a list of [`TypeSignature`]s. Coercion is attempted to match
-    /// the signatures in order, and stops after the first success, if any.
+    /// Matches exactly one of a list of [`TypeSignature`]s.
+    ///
+    /// Coercion is attempted to match the signatures in order, and stops after
+    /// the first success, if any.
     ///
     /// # Examples
-    /// Function `make_array` takes 0 or more arguments with arbitrary types, its `TypeSignature`
+    ///
+    /// Since `make_array` takes 0 or more arguments with arbitrary types, its `TypeSignature`
     /// is `OneOf(vec![Any(0), VariadicAny])`.
     OneOf(Vec<TypeSignature>),
-    /// Specifies Signatures for array functions
+    /// A function that has an [`ArrayFunctionSignature`]
     ArraySignature(ArrayFunctionSignature),
-    /// Fixed number of arguments of numeric types.
+    /// One or more arguments of numeric types.
+    ///
     /// See [`NativeType::is_numeric`] to know which type is considered numeric
     ///
-    /// [`NativeType::is_numeric`]: datafusion_common
+    /// For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
+    ///
+    /// [`NativeType::is_numeric`]: datafusion_common::types::NativeType::is_numeric
     Numeric(usize),
-    /// Fixed number of arguments of all the same string types.
+    /// One or arguments of all the same string types.
+    ///
     /// The precedence of type from high to low is Utf8View, LargeUtf8 and Utf8.
     /// Null is considered as `Utf8` by default
     /// Dictionary with string value type is also handled.
+    ///
+    /// For example, if a function is called with (utf8, large_utf8), all
+    /// arguments will be coerced to  `LargeUtf8`
+    ///
+    /// For functions that take no arguments (e.g. `random()` see [`TypeSignature::Nullary`]).
     String(usize),
-    /// Zero argument
-    NullAry,
+    /// No arguments
+    Nullary,
 }
 
 impl TypeSignature {
@@ -237,7 +265,7 @@ impl Display for ArrayFunctionSignature {
 impl TypeSignature {
     pub fn to_string_repr(&self) -> Vec<String> {
         match self {
-            TypeSignature::NullAry => {
+            TypeSignature::Nullary => {
                 vec!["NullAry()".to_string()]
             }
             TypeSignature::Variadic(types) => {
@@ -296,7 +324,7 @@ impl TypeSignature {
     pub fn supports_zero_argument(&self) -> bool {
         match &self {
             TypeSignature::Exact(vec) => vec.is_empty(),
-            TypeSignature::NullAry => true,
+            TypeSignature::Nullary => true,
             TypeSignature::OneOf(types) => types
                 .iter()
                 .any(|type_sig| type_sig.supports_zero_argument()),
@@ -362,7 +390,7 @@ impl TypeSignature {
             // TODO: Implement for other types
             TypeSignature::Any(_)
             | TypeSignature::Comparable(_)
-            | TypeSignature::NullAry
+            | TypeSignature::Nullary
             | TypeSignature::VariadicAny
             | TypeSignature::ArraySignature(_)
             | TypeSignature::UserDefined => vec![],
@@ -496,7 +524,7 @@ impl Signature {
 
     pub fn nullary(volatility: Volatility) -> Self {
         Signature {
-            type_signature: TypeSignature::NullAry,
+            type_signature: TypeSignature::Nullary,
             volatility,
         }
     }
@@ -573,10 +601,10 @@ mod tests {
             TypeSignature::Exact(vec![]),
             TypeSignature::OneOf(vec![
                 TypeSignature::Exact(vec![DataType::Int8]),
-                TypeSignature::NullAry,
+                TypeSignature::Nullary,
                 TypeSignature::Uniform(1, vec![DataType::Int8]),
             ]),
-            TypeSignature::NullAry,
+            TypeSignature::Nullary,
         ];
 
         for case in positive_cases {

datafusion/expr-common/src/type_coercion/binary.rs

@@ -642,7 +642,7 @@ pub fn comparison_coercion(lhs_type: &DataType, rhs_type: &DataType) -> Option<D
         .or_else(|| struct_coercion(lhs_type, rhs_type))
 }
 
-// Similar to comparison_coercion but prefer numeric if compares with numeric and string
+/// Similar to [`comparison_coercion`] but prefer numeric if compares with numeric and string
 pub fn comparison_coercion_numeric(
     lhs_type: &DataType,
     rhs_type: &DataType,