Migrate documentation for all math functions from scalar_functions.md…

… to code (#12908) * migrate: math doc from static to code gen * remove: documentation for pow * use: fmt * rm: unused import --------- Co-authored-by: Andrew Lamb <andrew@nerdnetworks.org>
apache · Oct 15, 2024 · a9b202c · a9b202c
1 parent beb1034
commit a9b202c
Show file tree

Hide file tree

Showing 18 changed files with 1,221 additions and 585 deletions.
diff --git a/datafusion/functions/src/macros.rs b/datafusion/functions/src/macros.rs
@@ -161,7 +161,7 @@ macro_rules! downcast_arg {
 /// $UNARY_FUNC: the unary function to apply to the argument
 /// $OUTPUT_ORDERING: the output ordering calculation method of the function
 macro_rules! make_math_unary_udf {
-    ($UDF:ident, $GNAME:ident, $NAME:ident, $UNARY_FUNC:ident, $OUTPUT_ORDERING:expr, $EVALUATE_BOUNDS:expr) => {
+    ($UDF:ident, $GNAME:ident, $NAME:ident, $UNARY_FUNC:ident, $OUTPUT_ORDERING:expr, $EVALUATE_BOUNDS:expr, $GET_DOC:expr) => {
         make_udf_function!($NAME::$UDF, $GNAME, $NAME);
 
         mod $NAME {
@@ -173,7 +173,9 @@ macro_rules! make_math_unary_udf {
             use datafusion_common::{exec_err, DataFusionError, Result};
             use datafusion_expr::interval_arithmetic::Interval;
             use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
-            use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility};
+            use datafusion_expr::{
+                ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+            };
 
             #[derive(Debug)]
             pub struct $UDF {
@@ -257,6 +259,10 @@ macro_rules! make_math_unary_udf {
                     };
                     Ok(ColumnarValue::Array(arr))
                 }
+
+                fn documentation(&self) -> Option<&Documentation> {
+                    Some($GET_DOC())
+                }
             }
         }
     };
@@ -273,7 +279,7 @@ macro_rules! make_math_unary_udf {
 /// $BINARY_FUNC: the binary function to apply to the argument
 /// $OUTPUT_ORDERING: the output ordering calculation method of the function
 macro_rules! make_math_binary_udf {
-    ($UDF:ident, $GNAME:ident, $NAME:ident, $BINARY_FUNC:ident, $OUTPUT_ORDERING:expr) => {
+    ($UDF:ident, $GNAME:ident, $NAME:ident, $BINARY_FUNC:ident, $OUTPUT_ORDERING:expr, $GET_DOC:expr) => {
         make_udf_function!($NAME::$UDF, $GNAME, $NAME);
 
         mod $NAME {
@@ -285,7 +291,9 @@ macro_rules! make_math_binary_udf {
             use datafusion_common::{exec_err, DataFusionError, Result};
             use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
             use datafusion_expr::TypeSignature;
-            use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility};
+            use datafusion_expr::{
+                ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+            };
 
             #[derive(Debug)]
             pub struct $UDF {
@@ -366,6 +374,10 @@ macro_rules! make_math_binary_udf {
                     };
                     Ok(ColumnarValue::Array(arr))
                 }
+
+                fn documentation(&self) -> Option<&Documentation> {
+                    Some($GET_DOC())
+                }
             }
         }
     };

diff --git a/datafusion/functions/src/math/abs.rs b/datafusion/functions/src/math/abs.rs
@@ -18,7 +18,7 @@
 //! math expressions
 
 use std::any::Any;
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
 
 use arrow::array::{
     ArrayRef, Decimal128Array, Decimal256Array, Float32Array, Float64Array, Int16Array,
@@ -28,8 +28,11 @@ use arrow::datatypes::DataType;
 use arrow::error::ArrowError;
 use datafusion_common::{exec_err, not_impl_err, DataFusionError, Result};
 use datafusion_expr::interval_arithmetic::Interval;
+use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
-use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility};
+use datafusion_expr::{
+    ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+};
 
 type MathArrayFunction = fn(&Vec<ArrayRef>) -> Result<ArrayRef>;
 
@@ -184,4 +187,22 @@ impl ScalarUDFImpl for AbsFunc {
             Ok(SortProperties::Unordered)
         }
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_abs_doc())
+    }
+}
+
+static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
+
+fn get_abs_doc() -> &'static Documentation {
+    DOCUMENTATION.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_MATH)
+            .with_description("Returns the absolute value of a number.")
+            .with_syntax_example("abs(numeric_expression)")
+            .with_standard_argument("numeric_expression", "Numeric")
+            .build()
+            .unwrap()
+    })
 }
diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs
@@ -20,14 +20,17 @@ use arrow::{
     error::ArrowError,
 };
 use std::any::Any;
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
 
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Int64;
 
 use crate::utils::make_scalar_function;
 use datafusion_common::{arrow_datafusion_err, exec_err, DataFusionError, Result};
-use datafusion_expr::{ColumnarValue, ScalarUDFImpl, Signature, Volatility};
+use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
+use datafusion_expr::{
+    ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+};
 
 #[derive(Debug)]
 pub struct FactorialFunc {
@@ -68,6 +71,24 @@ impl ScalarUDFImpl for FactorialFunc {
     fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> {
         make_scalar_function(factorial, vec![])(args)
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_factorial_doc())
+    }
+}
+
+static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
+
+fn get_factorial_doc() -> &'static Documentation {
+    DOCUMENTATION.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_MATH)
+            .with_description("Factorial. Returns 1 if value is less than 2.")
+            .with_syntax_example("factorial(numeric_expression)")
+            .with_standard_argument("numeric_expression", "Numeric")
+            .build()
+            .unwrap()
+    })
 }
 
 /// Factorial SQL function

diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs
@@ -19,15 +19,17 @@ use arrow::array::{ArrayRef, Int64Array};
 use arrow::error::ArrowError;
 use std::any::Any;
 use std::mem::swap;
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
 
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Int64;
 
 use crate::utils::make_scalar_function;
 use datafusion_common::{arrow_datafusion_err, exec_err, DataFusionError, Result};
-use datafusion_expr::ColumnarValue;
-use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
+use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
+use datafusion_expr::{
+    ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+};
 
 #[derive(Debug)]
 pub struct GcdFunc {
@@ -69,6 +71,27 @@ impl ScalarUDFImpl for GcdFunc {
     fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> {
         make_scalar_function(gcd, vec![])(args)
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_gcd_doc())
+    }
+}
+
+static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
+
+fn get_gcd_doc() -> &'static Documentation {
+    DOCUMENTATION.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_MATH)
+            .with_description(
+                "Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero.",
+            )
+            .with_syntax_example("gcd(expression_x, expression_y)")
+            .with_standard_argument("expression_x", "First numeric")
+            .with_standard_argument("expression_y", "Second numeric")
+            .build()
+            .unwrap()
+    })
 }
 
 /// Gcd SQL function

diff --git a/datafusion/functions/src/math/iszero.rs b/datafusion/functions/src/math/iszero.rs
@@ -16,16 +16,18 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
 
 use arrow::array::{ArrayRef, AsArray, BooleanArray};
 use arrow::datatypes::DataType::{Boolean, Float32, Float64};
 use arrow::datatypes::{DataType, Float32Type, Float64Type};
 
 use datafusion_common::{exec_err, Result};
-use datafusion_expr::ColumnarValue;
+use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::TypeSignature::Exact;
-use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
+use datafusion_expr::{
+    ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+};
 
 use crate::utils::make_scalar_function;
 
@@ -72,6 +74,26 @@ impl ScalarUDFImpl for IsZeroFunc {
     fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> {
         make_scalar_function(iszero, vec![])(args)
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_iszero_doc())
+    }
+}
+
+static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
+
+fn get_iszero_doc() -> &'static Documentation {
+    DOCUMENTATION.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_MATH)
+            .with_description(
+                "Returns true if a given number is +0.0 or -0.0 otherwise returns false.",
+            )
+            .with_syntax_example("iszero(numeric_expression)")
+            .with_standard_argument("numeric_expression", "Numeric")
+            .build()
+            .unwrap()
+    })
 }
 
 /// Iszero SQL function

diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs
@@ -16,16 +16,18 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
 
 use arrow::array::{ArrayRef, Int64Array};
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Int64;
 
 use arrow::error::ArrowError;
 use datafusion_common::{arrow_datafusion_err, exec_err, DataFusionError, Result};
-use datafusion_expr::ColumnarValue;
-use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
+use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
+use datafusion_expr::{
+    ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
+};
 
 use super::gcd::unsigned_gcd;
 use crate::utils::make_scalar_function;
@@ -70,6 +72,27 @@ impl ScalarUDFImpl for LcmFunc {
     fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> {
         make_scalar_function(lcm, vec![])(args)
     }
+
+    fn documentation(&self) -> Option<&Documentation> {
+        Some(get_lcm_doc())
+    }
+}
+
+static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
+
+fn get_lcm_doc() -> &'static Documentation {
+    DOCUMENTATION.get_or_init(|| {
+        Documentation::builder()
+            .with_doc_section(DOC_SECTION_MATH)
+            .with_description(
+                "Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero.",
+            )
+            .with_syntax_example("lcm(expression_x, expression_y)")
+            .with_standard_argument("expression_x", "First numeric")
+            .with_standard_argument("expression_y", "Second numeric")
+            .build()
+            .unwrap()
+    })
 }
 
 /// Lcm SQL function