Skip to content

Commit 802e025

Browse files
author
Cheng-Yuan-Lai
committed
doc-gen: migrate scalar functions (math) documentation 2/2
1 parent b9cef8c commit 802e025

File tree

7 files changed

+87
-135
lines changed

7 files changed

+87
-135
lines changed

‎datafusion/functions/src/math/nanvl.rs

+17-19
Original file line numberDiff line numberDiff line change
@@ -16,20 +16,34 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::{Arc, OnceLock};
19+
use std::sync::Arc;
2020

2121
use crate::utils::make_scalar_function;
2222

2323
use arrow::array::{ArrayRef, AsArray, Float32Array, Float64Array};
2424
use arrow::datatypes::DataType::{Float32, Float64};
2525
use arrow::datatypes::{DataType, Float32Type, Float64Type};
2626
use datafusion_common::{exec_err, DataFusionError, Result};
27-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
2827
use datafusion_expr::TypeSignature::Exact;
2928
use datafusion_expr::{
3029
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
3130
};
31+
use datafusion_macros::user_doc;
3232

33+
#[user_doc(
34+
doc_section(label = "Math Functions"),
35+
description = r#"Returns the first argument if it's not _NaN_.
36+
Returns the second argument otherwise."#,
37+
syntax_example = "nanvl(expression_x, expression_y)",
38+
argument(
39+
name = "expression_x",
40+
description = "Numeric expression to return if it's not _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators."
41+
),
42+
argument(
43+
name = "expression_y",
44+
description = "Numeric expression to return if the first expression is _NaN_. Can be a constant, column, or function, and any combination of arithmetic operators."
45+
)
46+
)]
3347
#[derive(Debug)]
3448
pub struct NanvlFunc {
3549
signature: Signature,
@@ -82,26 +96,10 @@ impl ScalarUDFImpl for NanvlFunc {
8296
}
8397

8498
fn documentation(&self) -> Option<&Documentation> {
85-
Some(get_nanvl_doc())
99+
self.doc()
86100
}
87101
}
88102

89-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
90-
91-
fn get_nanvl_doc() -> &'static Documentation {
92-
DOCUMENTATION.get_or_init(|| {
93-
Documentation::builder(
94-
DOC_SECTION_MATH,
95-
r#"Returns the first argument if it's not _NaN_.
96-
Returns the second argument otherwise."#,
97-
98-
"nanvl(expression_x, expression_y)")
99-
.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.")
100-
.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.")
101-
.build()
102-
})
103-
}
104-
105103
/// Nanvl SQL function
106104
fn nanvl(args: &[ArrayRef]) -> Result<ArrayRef> {
107105
match args[0].data_type() {

‎datafusion/functions/src/math/pi.rs

+7-16
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,21 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::OnceLock;
2019

2120
use arrow::datatypes::DataType;
2221
use arrow::datatypes::DataType::Float64;
2322
use datafusion_common::{internal_err, Result, ScalarValue};
24-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
2523
use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
2624
use datafusion_expr::{
2725
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
2826
};
27+
use datafusion_macros::user_doc;
2928

29+
#[user_doc(
30+
doc_section(label = "Math Functions"),
31+
description = "Returns an approximate value of π.",
32+
syntax_example = "pi()"
33+
)]
3034
#[derive(Debug)]
3135
pub struct PiFunc {
3236
signature: Signature,
@@ -82,19 +86,6 @@ impl ScalarUDFImpl for PiFunc {
8286
}
8387

8488
fn documentation(&self) -> Option<&Documentation> {
85-
Some(get_pi_doc())
89+
self.doc()
8690
}
8791
}
88-
89-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
90-
91-
fn get_pi_doc() -> &'static Documentation {
92-
DOCUMENTATION.get_or_init(|| {
93-
Documentation::builder(
94-
DOC_SECTION_MATH,
95-
"Returns an approximate value of π.",
96-
"pi()",
97-
)
98-
.build()
99-
})
100-
}

‎datafusion/functions/src/math/power.rs

+11-19
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717

1818
//! Math function: `power()`.
1919
use std::any::Any;
20-
use std::sync::{Arc, OnceLock};
20+
use std::sync::Arc;
2121

2222
use super::log::LogFunc;
2323

@@ -28,11 +28,18 @@ use datafusion_common::{
2828
plan_datafusion_err, DataFusionError, Result, ScalarValue,
2929
};
3030
use datafusion_expr::expr::ScalarFunction;
31-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
3231
use datafusion_expr::simplify::{ExprSimplifyResult, SimplifyInfo};
3332
use datafusion_expr::{ColumnarValue, Documentation, Expr, ScalarUDF, TypeSignature};
3433
use datafusion_expr::{ScalarUDFImpl, Signature, Volatility};
35-
34+
use datafusion_macros::user_doc;
35+
36+
#[user_doc(
37+
doc_section(label = "Math Functions"),
38+
description = "Returns a base expression raised to the power of an exponent.",
39+
syntax_example = "power(base, exponent)",
40+
standard_argument(name = "base", prefix = "Numeric"),
41+
standard_argument(name = "exponent", prefix = "Exponent numeric")
42+
)]
3643
#[derive(Debug)]
3744
pub struct PowerFunc {
3845
signature: Signature,
@@ -170,25 +177,10 @@ impl ScalarUDFImpl for PowerFunc {
170177
}
171178

172179
fn documentation(&self) -> Option<&Documentation> {
173-
Some(get_power_doc())
180+
self.doc()
174181
}
175182
}
176183

177-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
178-
179-
fn get_power_doc() -> &'static Documentation {
180-
DOCUMENTATION.get_or_init(|| {
181-
Documentation::builder(
182-
DOC_SECTION_MATH,
183-
"Returns a base expression raised to the power of an exponent.",
184-
"power(base, exponent)",
185-
)
186-
.with_standard_argument("base", Some("Numeric"))
187-
.with_standard_argument("exponent", Some("Exponent numeric"))
188-
.build()
189-
})
190-
}
191-
192184
/// Return true if this function call is a call to `Log`
193185
fn is_log(func: &ScalarUDF) -> bool {
194186
func.inner().as_any().downcast_ref::<LogFunc>().is_some()

‎datafusion/functions/src/math/random.rs

+9-17
Original file line numberDiff line numberDiff line change
@@ -16,18 +16,24 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::{Arc, OnceLock};
19+
use std::sync::Arc;
2020

2121
use arrow::array::Float64Array;
2222
use arrow::datatypes::DataType;
2323
use arrow::datatypes::DataType::Float64;
2424
use rand::{thread_rng, Rng};
2525

2626
use datafusion_common::{internal_err, Result};
27-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
2827
use datafusion_expr::ColumnarValue;
2928
use datafusion_expr::{Documentation, ScalarUDFImpl, Signature, Volatility};
29+
use datafusion_macros::user_doc;
3030

31+
#[user_doc(
32+
doc_section(label = "Math Functions"),
33+
description = r#"Returns a random float value in the range [0, 1).
34+
The random seed is unique to each row."#,
35+
syntax_example = "random()"
36+
)]
3137
#[derive(Debug)]
3238
pub struct RandomFunc {
3339
signature: Signature,
@@ -82,20 +88,6 @@ impl ScalarUDFImpl for RandomFunc {
8288
}
8389

8490
fn documentation(&self) -> Option<&Documentation> {
85-
Some(get_random_doc())
91+
self.doc()
8692
}
8793
}
88-
89-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
90-
91-
fn get_random_doc() -> &'static Documentation {
92-
DOCUMENTATION.get_or_init(|| {
93-
Documentation::builder(
94-
DOC_SECTION_MATH,
95-
r#"Returns a random float value in the range [0, 1).
96-
The random seed is unique to each row."#,
97-
"random()",
98-
)
99-
.build()
100-
})
101-
}

‎datafusion/functions/src/math/round.rs

+14-22
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::{Arc, OnceLock};
19+
use std::sync::Arc;
2020

2121
use crate::utils::make_scalar_function;
2222

@@ -25,13 +25,23 @@ use arrow::compute::{cast_with_options, CastOptions};
2525
use arrow::datatypes::DataType::{Float32, Float64, Int32};
2626
use arrow::datatypes::{DataType, Float32Type, Float64Type, Int32Type};
2727
use datafusion_common::{exec_datafusion_err, exec_err, Result, ScalarValue};
28-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
2928
use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
3029
use datafusion_expr::TypeSignature::Exact;
3130
use datafusion_expr::{
3231
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
3332
};
34-
33+
use datafusion_macros::user_doc;
34+
35+
#[user_doc(
36+
doc_section(label = "Math Functions"),
37+
description = "Rounds a number to the nearest integer.",
38+
syntax_example = "round(numeric_expression[, decimal_places])",
39+
standard_argument(name = "numeric_expression", prefix = "Numeric"),
40+
argument(
41+
name = "decimal_places",
42+
description = "Optional. The number of decimal places to round to. Defaults to 0."
43+
)
44+
)]
3545
#[derive(Debug)]
3646
pub struct RoundFunc {
3747
signature: Signature,
@@ -104,28 +114,10 @@ impl ScalarUDFImpl for RoundFunc {
104114
}
105115

106116
fn documentation(&self) -> Option<&Documentation> {
107-
Some(get_round_doc())
117+
self.doc()
108118
}
109119
}
110120

111-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
112-
113-
fn get_round_doc() -> &'static Documentation {
114-
DOCUMENTATION.get_or_init(|| {
115-
Documentation::builder(
116-
DOC_SECTION_MATH,
117-
"Rounds a number to the nearest integer.",
118-
"round(numeric_expression[, decimal_places])",
119-
)
120-
.with_standard_argument("numeric_expression", Some("Numeric"))
121-
.with_argument(
122-
"decimal_places",
123-
"Optional. The number of decimal places to round to. Defaults to 0.",
124-
)
125-
.build()
126-
})
127-
}
128-
129121
/// Round SQL function
130122
pub fn round(args: &[ArrayRef]) -> Result<ArrayRef> {
131123
if args.len() != 1 && args.len() != 2 {

‎datafusion/functions/src/math/signum.rs

+11-19
Original file line numberDiff line numberDiff line change
@@ -16,21 +16,29 @@
1616
// under the License.
1717

1818
use std::any::Any;
19-
use std::sync::{Arc, OnceLock};
19+
use std::sync::Arc;
2020

2121
use arrow::array::{ArrayRef, AsArray};
2222
use arrow::datatypes::DataType::{Float32, Float64};
2323
use arrow::datatypes::{DataType, Float32Type, Float64Type};
2424

2525
use datafusion_common::{exec_err, Result};
26-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_MATH;
2726
use datafusion_expr::sort_properties::{ExprProperties, SortProperties};
2827
use datafusion_expr::{
2928
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
3029
};
30+
use datafusion_macros::user_doc;
3131

3232
use crate::utils::make_scalar_function;
3333

34+
#[user_doc(
35+
doc_section(label = "Math Functions"),
36+
description = r#"Returns the sign of a number.
37+
Negative numbers return `-1`.
38+
Zero and positive numbers return `1`."#,
39+
syntax_example = "signum(numeric_expression)",
40+
standard_argument(name = "numeric_expression", prefix = "Numeric")
41+
)]
3442
#[derive(Debug)]
3543
pub struct SignumFunc {
3644
signature: Signature,
@@ -89,26 +97,10 @@ impl ScalarUDFImpl for SignumFunc {
8997
}
9098

9199
fn documentation(&self) -> Option<&Documentation> {
92-
Some(get_signum_doc())
100+
self.doc()
93101
}
94102
}
95103

96-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
97-
98-
fn get_signum_doc() -> &'static Documentation {
99-
DOCUMENTATION.get_or_init(|| {
100-
Documentation::builder(
101-
DOC_SECTION_MATH,
102-
r#"Returns the sign of a number.
103-
Negative numbers return `-1`.
104-
Zero and positive numbers return `1`."#,
105-
"signum(numeric_expression)",
106-
)
107-
.with_standard_argument("numeric_expression", Some("Numeric"))
108-
.build()
109-
})
110-
}
111-
112104
/// signum SQL function
113105
pub fn signum(args: &[ArrayRef]) -> Result<ArrayRef> {
114106
match args[0].data_type() {

0 commit comments

Comments
 (0)