This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new fce3fb3033 doc-gen: migrate scalar functions (math) documentation 2/2
(#13923)
fce3fb3033 is described below
commit fce3fb3033ae50e8590e075ffb11422112128233
Author: Ian Lai <[email protected]>
AuthorDate: Sun Dec 29 22:40:11 2024 +0800
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>
---
datafusion/functions/src/math/nanvl.rs | 36 ++++++++++++++---------------
datafusion/functions/src/math/pi.rs | 23 ++++++------------
datafusion/functions/src/math/power.rs | 30 +++++++++---------------
datafusion/functions/src/math/random.rs | 26 ++++++++-------------
datafusion/functions/src/math/round.rs | 36 +++++++++++------------------
datafusion/functions/src/math/signum.rs | 30 +++++++++---------------
datafusion/functions/src/math/trunc.rs | 41 +++++++++++++++------------------
7 files changed, 87 insertions(+), 135 deletions(-)
diff --git a/datafusion/functions/src/math/nanvl.rs
b/datafusion/functions/src/math/nanvl.rs
index 0715dc7f7e..33823acce7 100644
--- a/datafusion/functions/src/math/nanvl.rs
+++ b/datafusion/functions/src/math/nanvl.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;
@@ -24,12 +24,26 @@ 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
index a96ca17662..06f7a01544 100644
--- 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
index 296b2dd3fe..7fab858d34 100644
--- 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
index e34db023ed..197d065ea4 100644
--- a/datafusion/functions/src/math/random.rs
+++ b/datafusion/functions/src/math/random.rs
@@ -16,7 +16,7 @@
// under the License.
use std::any::Any;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
use arrow::array::Float64Array;
use arrow::datatypes::DataType;
@@ -24,10 +24,16 @@ 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
index cfbf083fcb..b3442c321c 100644
--- 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
index eda9df49fb..f68834db37 100644
--- 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() {
diff --git a/datafusion/functions/src/math/trunc.rs
b/datafusion/functions/src/math/trunc.rs
index c2787c4577..8d791370d7 100644
--- a/datafusion/functions/src/math/trunc.rs
+++ b/datafusion/functions/src/math/trunc.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,27 @@ use arrow::datatypes::DataType::{Float32, Float64};
use arrow::datatypes::{DataType, Float32Type, Float64Type, Int64Type};
use datafusion_common::ScalarValue::Int64;
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::TypeSignature::Exact;
use datafusion_expr::{
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
};
-
+use datafusion_macros::user_doc;
+
+#[user_doc(
+ doc_section(label = "Math Functions"),
+ description = "Truncates a number to a whole number or truncated to the
specified decimal places.",
+ syntax_example = "trunc(numeric_expression[, decimal_places])",
+ standard_argument(name = "numeric_expression", prefix = "Numeric"),
+ argument(
+ name = "decimal_places",
+ description = r#"Optional. The number of decimal places to
+ truncate to. Defaults to 0 (truncate to a whole number). If
+ `decimal_places` is a positive integer, truncates digits to the
+ right of the decimal point. If `decimal_places` is a negative
+ integer, replaces digits to the left of the decimal point with `0`."#
+ )
+)]
#[derive(Debug)]
pub struct TruncFunc {
signature: Signature,
@@ -109,29 +123,10 @@ impl ScalarUDFImpl for TruncFunc {
}
fn documentation(&self) -> Option<&Documentation> {
- Some(get_trunc_doc())
+ self.doc()
}
}
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_trunc_doc() -> &'static Documentation {
- DOCUMENTATION.get_or_init(|| {
- Documentation::builder(
- DOC_SECTION_MATH,
- "Truncates a number to a whole number or truncated to the
specified decimal places.",
-
- "trunc(numeric_expression[, decimal_places])")
- .with_standard_argument("numeric_expression", Some("Numeric"))
- .with_argument("decimal_places", r#"Optional. The number of
decimal places to
- truncate to. Defaults to 0 (truncate to a whole number). If
- `decimal_places` is a positive integer, truncates digits to the
- right of the decimal point. If `decimal_places` is a negative
- integer, replaces digits to the left of the decimal point with `0`."#)
- .build()
- })
-}
-
/// Truncate(numeric, decimalPrecision) and trunc(numeric) SQL function
fn trunc(args: &[ArrayRef]) -> Result<ArrayRef> {
if args.len() != 1 && args.len() != 2 {
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
