doc-gen: migrate scalar functions (math) documentation 1/2

Chen-Yuan-Lai · Dec 27, 2024 · 87cadce · 87cadce
1 parent a08dc0a
commit 87cadce
Show file tree

Hide file tree

Showing 7 changed files with 71 additions and 126 deletions.
diff --git a/datafusion/functions/src/math/cot.rs b/datafusion/functions/src/math/cot.rs
@@ -16,18 +16,24 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use arrow::array::{ArrayRef, AsArray};
 use arrow::datatypes::DataType::{Float32, Float64};
 use arrow::datatypes::{DataType, Float32Type, Float64Type};
 
 use crate::utils::make_scalar_function;
 use datafusion_common::{exec_err, Result};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::{ColumnarValue, Documentation};
 use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
-
+use datafusion_macros::user_doc;
+
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns the cotangent of a number.",
+    syntax_example = r#"cot(numeric_expression)"#,
+    standard_argument(name = "numeric_expression", prefix = "Numeric")
+)]
 #[derive(Debug)]
 pub struct CotFunc {
     signature: Signature,
@@ -39,20 +45,6 @@ impl Default for CotFunc {
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_cot_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Returns the cotangent of a number.",
-            r#"cot(numeric_expression)"#,
-        )
-        .with_standard_argument("numeric_expression", Some("Numeric"))
-        .build()
-    })
-}
-
 impl CotFunc {
     pub fn new() -> Self {
         use DataType::*;
@@ -92,7 +84,7 @@ impl ScalarUDFImpl for CotFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_cot_doc())
+        self.doc()
     }
 
     fn invoke_batch(

diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs
@@ -20,7 +20,7 @@ use arrow::{
     error::ArrowError,
 };
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Int64;
@@ -29,11 +29,17 @@ use crate::utils::make_scalar_function;
 use datafusion_common::{
     arrow_datafusion_err, exec_err, internal_datafusion_err, DataFusionError, Result,
 };
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
-
+use datafusion_macros::user_doc;
+
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Factorial. Returns 1 if value is less than 2.",
+    syntax_example = "factorial(numeric_expression)",
+    standard_argument(name = "numeric_expression", prefix = "Numeric")
+)]
 #[derive(Debug)]
 pub struct FactorialFunc {
     signature: Signature,
@@ -79,24 +85,10 @@ impl ScalarUDFImpl for FactorialFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_factorial_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_factorial_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Factorial. Returns 1 if value is less than 2.",
-            "factorial(numeric_expression)",
-        )
-        .with_standard_argument("numeric_expression", Some("Numeric"))
-        .build()
-    })
-}
-
 /// Factorial SQL function
 fn factorial(args: &[ArrayRef]) -> Result<ArrayRef> {
     match args[0].data_type() {

diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs
@@ -19,7 +19,7 @@ use arrow::array::{ArrayRef, Int64Array};
 use arrow::error::ArrowError;
 use std::any::Any;
 use std::mem::swap;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Int64;
@@ -28,11 +28,18 @@ use crate::utils::make_scalar_function;
 use datafusion_common::{
     arrow_datafusion_err, exec_err, internal_datafusion_err, DataFusionError, Result,
 };
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
-
+use datafusion_macros::user_doc;
+
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero..",
+    syntax_example = "gcd(expression_x, expression_y)",
+    standard_argument(name = "expression_x", prefix = "First numeric"),
+    standard_argument(name = "expression_y", prefix = "Second numeric")
+)]
 #[derive(Debug)]
 pub struct GcdFunc {
     signature: Signature,
@@ -79,25 +86,10 @@ impl ScalarUDFImpl for GcdFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_gcd_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_gcd_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-                "Returns the greatest common divisor of `expression_x` and `expression_y`. Returns 0 if both inputs are zero.",
-
-            "gcd(expression_x, expression_y)")
-            .with_standard_argument("expression_x", Some("First numeric"))
-            .with_standard_argument("expression_y", Some("Second numeric"))
-            .build()
-    })
-}
-
 /// Gcd SQL function
 fn gcd(args: &[ArrayRef]) -> Result<ArrayRef> {
     match args[0].data_type() {

diff --git a/datafusion/functions/src/math/iszero.rs b/datafusion/functions/src/math/iszero.rs
@@ -16,21 +16,27 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 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::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::TypeSignature::Exact;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 
 use crate::utils::make_scalar_function;
 
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns true if a given number is +0.0 or -0.0 otherwise returns false.",
+    syntax_example = "iszero(numeric_expression)",
+    standard_argument(name = "numeric_expression", prefix = "Numeric")
+)]
 #[derive(Debug)]
 pub struct IsZeroFunc {
     signature: Signature,
@@ -80,24 +86,10 @@ impl ScalarUDFImpl for IsZeroFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_iszero_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_iszero_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Returns true if a given number is +0.0 or -0.0 otherwise returns false.",
-            "iszero(numeric_expression)",
-        )
-        .with_standard_argument("numeric_expression", Some("Numeric"))
-        .build()
-    })
-}
-
 /// Iszero SQL function
 pub fn iszero(args: &[ArrayRef]) -> Result<ArrayRef> {
     match args[0].data_type() {

diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs
@@ -16,7 +16,7 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use arrow::array::{ArrayRef, Int64Array};
 use arrow::datatypes::DataType;
@@ -26,14 +26,21 @@ use arrow::error::ArrowError;
 use datafusion_common::{
     arrow_datafusion_err, exec_err, internal_datafusion_err, DataFusionError, Result,
 };
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 
 use super::gcd::unsigned_gcd;
 use crate::utils::make_scalar_function;
 
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero.",
+    syntax_example = "lcm(expression_x, expression_y)",
+    standard_argument(name = "expression_x", prefix = "First numeric"),
+    standard_argument(name = "expression_y", prefix = "Second numeric")
+)]
 #[derive(Debug)]
 pub struct LcmFunc {
     signature: Signature,
@@ -80,25 +87,10 @@ impl ScalarUDFImpl for LcmFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_lcm_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_lcm_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-                "Returns the least common multiple of `expression_x` and `expression_y`. Returns 0 if either input is zero.",
-
-            "lcm(expression_x, expression_y)")
-            .with_standard_argument("expression_x", Some("First numeric"))
-            .with_standard_argument("expression_y", Some("Second numeric"))
-            .build()
-    })
-}
-
 /// Lcm SQL function
 fn lcm(args: &[ArrayRef]) -> Result<ArrayRef> {
     let compute_lcm = |x: i64, y: i64| {

diff --git a/datafusion/functions/src/math/log.rs b/datafusion/functions/src/math/log.rs
@@ -18,7 +18,7 @@
 //! Math function: `log()`.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use super::power::PowerFunc;
 
@@ -28,14 +28,22 @@ use datafusion_common::{
     exec_err, internal_err, plan_datafusion_err, plan_err, Result, ScalarValue,
 };
 use datafusion_expr::expr::ScalarFunction;
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo};
 use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
 use datafusion_expr::{
     lit, ColumnarValue, Documentation, Expr, ScalarUDF, TypeSignature::*,
 };
 use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
-
+use datafusion_macros::user_doc;
+
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number.",
+    syntax_example = r#"log(base, numeric_expression)
+log(numeric_expression)"#,
+    standard_argument(name = "base", prefix = "Base numeric"),
+    standard_argument(name = "numeric_expression", prefix = "Numeric")
+)]
 #[derive(Debug)]
 pub struct LogFunc {
     signature: Signature,
@@ -47,21 +55,6 @@ impl Default for LogFunc {
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_log_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Returns the base-x logarithm of a number. Can either provide a specified base, or if omitted then takes the base-10 of a number.",
-            r#"log(base, numeric_expression)
-log(numeric_expression)"#)
-            .with_standard_argument("base", Some("Base numeric"))
-            .with_standard_argument("numeric_expression", Some("Numeric"))
-            .build()
-    })
-}
-
 impl LogFunc {
     pub fn new() -> Self {
         use DataType::*;
@@ -189,7 +182,7 @@ impl ScalarUDFImpl for LogFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_log_doc())
+        self.doc()
     }
 
     /// Simplify the `log` function by the relevant rules:

diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs
@@ -22,11 +22,17 @@ use datafusion_common::{exec_err, Result};
 use datafusion_expr::{ColumnarValue, TypeSignature};
 
 use arrow::array::{ArrayRef, AsArray, BooleanArray};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::{Documentation, ScalarUDFImpl, Signature, Volatility};
+use datafusion_macros::user_doc;
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns true if a given number is +NaN or -NaN otherwise returns false.",
+    syntax_example = "isnan(numeric_expression)",
+    standard_argument(name = "numeric_expression", prefix = "Numeric")
+)]
 #[derive(Debug)]
 pub struct IsNanFunc {
     signature: Signature,
@@ -97,20 +103,6 @@ impl ScalarUDFImpl for IsNanFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_isnan_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_isnan_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Returns true if a given number is +NaN or -NaN otherwise returns false.",
-            "isnan(numeric_expression)",
-        )
-        .with_standard_argument("numeric_expression", Some("Numeric"))
-        .build()
-    })
-}