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

* doc-gen: migrate scalar functions (math) documentation 2/2 * fix: fix typo --------- Co-authored-by: Cheng-Yuan-Lai <a186235@g,ail.com>
apache · Dec 29, 2024 · fce3fb3 · fce3fb3
1 parent 4290f36
commit fce3fb3
Show file tree

Hide file tree

Showing 7 changed files with 87 additions and 135 deletions.
diff --git a/datafusion/functions/src/math/nanvl.rs b/datafusion/functions/src/math/nanvl.rs
@@ -16,20 +16,34 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use crate::utils::make_scalar_function;
 
 use arrow::array::{ArrayRef, AsArray, Float32Array, Float64Array};
 use arrow::datatypes::DataType::{Float32, Float64};
 use arrow::datatypes::{DataType, Float32Type, Float64Type};
 use datafusion_common::{exec_err, DataFusionError, 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;
 
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = r#"Returns the first argument if it's not _NaN_.
+Returns the second argument otherwise."#,
+    syntax_example = "nanvl(expression_x, expression_y)",
+    argument(
+        name = "expression_x",
+        description = "Numeric expression to return if it's not _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators."
+    ),
+    argument(
+        name = "expression_y",
+        description = "Numeric expression to return if the first expression is _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators."
+    )
+)]
 #[derive(Debug)]
 pub struct NanvlFunc {
     signature: Signature,
@@ -82,26 +96,10 @@ impl ScalarUDFImpl for NanvlFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_nanvl_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_nanvl_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-                r#"Returns the first argument if it's not _NaN_.
-Returns the second argument otherwise."#,
-
-            "nanvl(expression_x, expression_y)")
-            .with_argument("expression_x", "Numeric expression to return if it's not _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators.")
-            .with_argument("expression_y", "Numeric expression to return if the first expression is _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators.")
-            .build()
-    })
-}
-
 /// Nanvl SQL function
 fn nanvl(args: &[ArrayRef]) -> Result<ArrayRef> {
     match args[0].data_type() {

diff --git a/datafusion/functions/src/math/pi.rs b/datafusion/functions/src/math/pi.rs
@@ -16,17 +16,21 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::OnceLock;
 
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Float64;
 use datafusion_common::{internal_err, Result, ScalarValue};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Returns an approximate value of π.",
+    syntax_example = "pi()"
+)]
 #[derive(Debug)]
 pub struct PiFunc {
     signature: Signature,
@@ -82,19 +86,6 @@ impl ScalarUDFImpl for PiFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_pi_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_pi_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Returns an approximate value of π.",
-            "pi()",
-        )
-        .build()
-    })
-}
diff --git a/datafusion/functions/src/math/power.rs b/datafusion/functions/src/math/power.rs
@@ -17,7 +17,7 @@
 
 //! Math function: `power()`.
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use super::log::LogFunc;
 
@@ -28,11 +28,18 @@ use datafusion_common::{
     plan_datafusion_err, DataFusionError, 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::{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 a base expression raised to the power of an exponent.",
+    syntax_example = "power(base, exponent)",
+    standard_argument(name = "base", prefix = "Numeric"),
+    standard_argument(name = "exponent", prefix = "Exponent numeric")
+)]
 #[derive(Debug)]
 pub struct PowerFunc {
     signature: Signature,
@@ -170,25 +177,10 @@ impl ScalarUDFImpl for PowerFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_power_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_power_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Returns a base expression raised to the power of an exponent.",
-            "power(base, exponent)",
-        )
-        .with_standard_argument("base", Some("Numeric"))
-        .with_standard_argument("exponent", Some("Exponent numeric"))
-        .build()
-    })
-}
-
 /// Return true if this function call is a call to `Log`
 fn is_log(func: &ScalarUDF) -> bool {
     func.inner().as_any().downcast_ref::<LogFunc>().is_some()

diff --git a/datafusion/functions/src/math/random.rs b/datafusion/functions/src/math/random.rs
@@ -16,18 +16,24 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use arrow::array::Float64Array;
 use arrow::datatypes::DataType;
 use arrow::datatypes::DataType::Float64;
 use rand::{thread_rng, Rng};
 
 use datafusion_common::{internal_err, Result};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::ColumnarValue;
 use datafusion_expr::{Documentation, ScalarUDFImpl, Signature, Volatility};
+use datafusion_macros::user_doc;
 
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = r#"Returns a random float value in the range [0, 1).
+The random seed is unique to each row."#,
+    syntax_example = "random()"
+)]
 #[derive(Debug)]
 pub struct RandomFunc {
     signature: Signature,
@@ -82,20 +88,6 @@ impl ScalarUDFImpl for RandomFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_random_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_random_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            r#"Returns a random float value in the range [0, 1).
-The random seed is unique to each row."#,
-            "random()",
-        )
-        .build()
-    })
-}
diff --git a/datafusion/functions/src/math/round.rs b/datafusion/functions/src/math/round.rs
@@ -16,7 +16,7 @@
 // under the License.
 
 use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use crate::utils::make_scalar_function;
 
@@ -25,13 +25,23 @@ use arrow::compute::{cast_with_options, CastOptions};
 use arrow::datatypes::DataType::{Float32, Float64, Int32};
 use arrow::datatypes::{DataType, Float32Type, Float64Type, Int32Type};
 use datafusion_common::{exec_datafusion_err, exec_err, Result, ScalarValue};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
 use datafusion_expr::TypeSignature::Exact;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
-
+use datafusion_macros::user_doc;
+
+#[user_doc(
+    doc_section(label = "Math Functions"),
+    description = "Rounds a number to the nearest integer.",
+    syntax_example = "round(numeric_expression[, decimal_places])",
+    standard_argument(name = "numeric_expression", prefix = "Numeric"),
+    argument(
+        name = "decimal_places",
+        description = "Optional. The number of decimal places to round to. Defaults to 0."
+    )
+)]
 #[derive(Debug)]
 pub struct RoundFunc {
     signature: Signature,
@@ -104,28 +114,10 @@ impl ScalarUDFImpl for RoundFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_round_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_round_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            "Rounds a number to the nearest integer.",
-            "round(numeric_expression[, decimal_places])",
-        )
-        .with_standard_argument("numeric_expression", Some("Numeric"))
-        .with_argument(
-            "decimal_places",
-            "Optional. The number of decimal places to round to. Defaults to 0.",
-        )
-        .build()
-    })
-}
-
 /// Round SQL function
 pub fn round(args: &[ArrayRef]) -> Result<ArrayRef> {
     if args.len() != 1 && args.len() != 2 {

diff --git a/datafusion/functions/src/math/signum.rs b/datafusion/functions/src/math/signum.rs
@@ -16,21 +16,29 @@
 // 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 datafusion_common::{exec_err, Result};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
 use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
 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 = r#"Returns the sign of a number.
+Negative numbers return `-1`.
+Zero and positive numbers return `1`."#,
+    syntax_example = "signum(numeric_expression)",
+    standard_argument(name = "numeric_expression", prefix = "Numeric")
+)]
 #[derive(Debug)]
 pub struct SignumFunc {
     signature: Signature,
@@ -89,26 +97,10 @@ impl ScalarUDFImpl for SignumFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_signum_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_signum_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_MATH,
-            r#"Returns the sign of a number.
-Negative numbers return `-1`.
-Zero and positive numbers return `1`."#,
-            "signum(numeric_expression)",
-        )
-        .with_standard_argument("numeric_expression", Some("Numeric"))
-        .build()
-    })
-}
-
 /// signum SQL function
 pub fn signum(args: &[ArrayRef]) -> Result<ArrayRef> {
     match args[0].data_type() {