diff --git a/datafusion/doc/src/lib.rs b/datafusion/doc/src/lib.rs index c4b0cbbae498..5bc986d07f8e 100644 --- a/datafusion/doc/src/lib.rs +++ b/datafusion/doc/src/lib.rs @@ -56,8 +56,12 @@ pub struct Documentation { impl Documentation { /// Returns a new [`DocumentationBuilder`] with no options set. - pub fn builder() -> DocumentationBuilder { - DocumentationBuilder::new() + pub fn builder( + doc_section: DocSection, + description: impl Into, + syntax_example: impl Into, + ) -> DocumentationBuilder { + DocumentationBuilder::new(doc_section, description, syntax_example) } } @@ -86,17 +90,14 @@ pub struct DocSection { /// description: None, /// }; /// -/// let documentation = Documentation::builder() -/// .with_doc_section(doc_section) -/// .with_description("Add one to an int32") -/// .with_syntax_example("add_one(2)") +/// let documentation = Documentation::builder(doc_section, "Add one to an int32".to_owned(), "add_one(2)".to_owned()) /// .with_argument("arg_1", "The int32 number to add one to") /// .build(); /// # } pub struct DocumentationBuilder { - pub doc_section: Option, - pub description: Option, - pub syntax_example: Option, + pub doc_section: DocSection, + pub description: String, + pub syntax_example: String, pub sql_example: Option, pub arguments: Option>, pub alternative_syntax: Option>, @@ -104,11 +105,15 @@ pub struct DocumentationBuilder { } impl DocumentationBuilder { - pub fn new() -> Self { + pub fn new( + doc_section: DocSection, + description: impl Into, + syntax_example: impl Into, + ) -> Self { Self { - doc_section: None, - description: None, - syntax_example: None, + doc_section, + description: description.into(), + syntax_example: syntax_example.into(), sql_example: None, arguments: None, alternative_syntax: None, @@ -117,17 +122,17 @@ impl DocumentationBuilder { } pub fn with_doc_section(mut self, doc_section: DocSection) -> Self { - self.doc_section = Some(doc_section); + self.doc_section = doc_section; self } pub fn with_description(mut self, description: impl Into) -> Self { - self.description = Some(description.into()); + self.description = description.into(); self } pub fn with_syntax_example(mut self, syntax_example: impl Into) -> Self { - self.syntax_example = Some(syntax_example.into()); + self.syntax_example = syntax_example.into(); self } @@ -205,20 +210,10 @@ impl DocumentationBuilder { related_udfs, } = self; - if doc_section.is_none() { - panic!("Documentation must have a doc section"); - } - if description.is_none() { - panic!("Documentation must have a description"); - } - if syntax_example.is_none() { - panic!("Documentation must have a syntax_example"); - } - Documentation { - doc_section: doc_section.unwrap(), - description: description.unwrap(), - syntax_example: syntax_example.unwrap(), + doc_section, + description, + syntax_example, sql_example, arguments, alternative_syntax, @@ -226,9 +221,3 @@ impl DocumentationBuilder { } } } - -impl Default for DocumentationBuilder { - fn default() -> Self { - Self::new() - } -} diff --git a/datafusion/expr/src/udaf.rs b/datafusion/expr/src/udaf.rs index 28506caceea2..56c9822495f8 100644 --- a/datafusion/expr/src/udaf.rs +++ b/datafusion/expr/src/udaf.rs @@ -333,10 +333,7 @@ where /// /// fn get_doc() -> &'static Documentation { /// DOCUMENTATION.get_or_init(|| { -/// Documentation::builder() -/// .with_doc_section(DOC_SECTION_AGGREGATE) -/// .with_description("calculates a geometric mean") -/// .with_syntax_example("geo_mean(2.0)") +/// Documentation::builder(DOC_SECTION_AGGREGATE, "calculates a geometric mean", "geo_mean(2.0)") /// .with_argument("arg1", "The Float64 number for the geometric mean") /// .build() /// }) diff --git a/datafusion/expr/src/udf.rs b/datafusion/expr/src/udf.rs index 8da4501f18a1..5493e43e1f1b 100644 --- a/datafusion/expr/src/udf.rs +++ b/datafusion/expr/src/udf.rs @@ -374,10 +374,7 @@ pub struct ScalarFunctionArgs<'a> { /// /// fn get_doc() -> &'static Documentation { /// DOCUMENTATION.get_or_init(|| { -/// Documentation::builder() -/// .with_doc_section(DOC_SECTION_MATH) -/// .with_description("Add one to an int32") -/// .with_syntax_example("add_one(2)") +/// Documentation::builder(DOC_SECTION_MATH, "Add one to an int32", "add_one(2)") /// .with_argument("arg1", "The int32 number to add one to") /// .build() /// }) diff --git a/datafusion/expr/src/udwf.rs b/datafusion/expr/src/udwf.rs index 11bc7043da76..4bfc3f07bb14 100644 --- a/datafusion/expr/src/udwf.rs +++ b/datafusion/expr/src/udwf.rs @@ -258,10 +258,7 @@ where /// /// fn get_doc() -> &'static Documentation { /// DOCUMENTATION.get_or_init(|| { -/// Documentation::builder() -/// .with_doc_section(DOC_SECTION_ANALYTICAL) -/// .with_description("smooths the windows") -/// .with_syntax_example("smooth_it(2)") +/// Documentation::builder(DOC_SECTION_ANALYTICAL, "smooths the windows", "smooth_it(2)") /// .with_argument("arg1", "The int32 number to smooth by") /// .build() /// }) diff --git a/datafusion/functions-aggregate/src/approx_distinct.rs b/datafusion/functions-aggregate/src/approx_distinct.rs index ef7b12768b75..e955cea9d1a0 100644 --- a/datafusion/functions-aggregate/src/approx_distinct.rs +++ b/datafusion/functions-aggregate/src/approx_distinct.rs @@ -317,12 +317,7 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_approx_distinct_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_APPROXIMATE) - .with_description( - "Returns the approximate number of distinct input values calculated using the HyperLogLog algorithm.", - ) - .with_syntax_example("approx_distinct(expression)") + Documentation::builder(DOC_SECTION_APPROXIMATE, "Returns the approximate number of distinct input values calculated using the HyperLogLog algorithm.", "approx_distinct(expression)") .with_sql_example(r#"```sql > SELECT approx_distinct(column_name) FROM table_name; +-----------------------------------+ diff --git a/datafusion/functions-aggregate/src/approx_median.rs b/datafusion/functions-aggregate/src/approx_median.rs index 3a33e725ec0a..8920c8e5f0c4 100644 --- a/datafusion/functions-aggregate/src/approx_median.rs +++ b/datafusion/functions-aggregate/src/approx_median.rs @@ -130,12 +130,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_approx_median_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_APPROXIMATE) - .with_description( + Documentation::builder( + DOC_SECTION_APPROXIMATE, "Returns the approximate median (50th percentile) of input values. It is an alias of `approx_percentile_cont(x, 0.5)`.", - ) - .with_syntax_example("approx_median(expression)") + + "approx_median(expression)") .with_sql_example(r#"```sql > SELECT approx_median(column_name) FROM table_name; +-----------------------------------+ diff --git a/datafusion/functions-aggregate/src/approx_percentile_cont.rs b/datafusion/functions-aggregate/src/approx_percentile_cont.rs index 8bc52f9a1bd0..6edae6344ab1 100644 --- a/datafusion/functions-aggregate/src/approx_percentile_cont.rs +++ b/datafusion/functions-aggregate/src/approx_percentile_cont.rs @@ -280,12 +280,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_approx_percentile_cont_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_APPROXIMATE) - .with_description( + Documentation::builder( + DOC_SECTION_APPROXIMATE, "Returns the approximate percentile of input values using the t-digest algorithm.", - ) - .with_syntax_example("approx_percentile_cont(expression, percentile, centroids)") + "approx_percentile_cont(expression, percentile, centroids)") .with_sql_example(r#"```sql > SELECT approx_percentile_cont(column_name, 0.75, 100) FROM table_name; +-------------------------------------------------+ diff --git a/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs b/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs index a309ff48ca53..7cf8d2dca13f 100644 --- a/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs +++ b/datafusion/functions-aggregate/src/approx_percentile_cont_with_weight.rs @@ -165,12 +165,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_approx_percentile_cont_with_weight_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_APPROXIMATE) - .with_description( + Documentation::builder( + DOC_SECTION_APPROXIMATE, "Returns the weighted approximate percentile of input values using the t-digest algorithm.", - ) - .with_syntax_example("approx_percentile_cont_with_weight(expression, weight, percentile)") + + "approx_percentile_cont_with_weight(expression, weight, percentile)") .with_sql_example(r#"```sql > SELECT approx_percentile_cont_with_weight(column_name, weight_column, 0.90) FROM table_name; +----------------------------------------------------------------------+ diff --git a/datafusion/functions-aggregate/src/array_agg.rs b/datafusion/functions-aggregate/src/array_agg.rs index dc57782ac2f3..3b9a521ec972 100644 --- a/datafusion/functions-aggregate/src/array_agg.rs +++ b/datafusion/functions-aggregate/src/array_agg.rs @@ -154,12 +154,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_agg_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( + Documentation::builder( + DOC_SECTION_GENERAL, "Returns an array created from the expression elements. If ordering is required, elements are inserted in the specified order.", - ) - .with_syntax_example("array_agg(expression [ORDER BY expression])") + + "array_agg(expression [ORDER BY expression])") .with_sql_example(r#"```sql > SELECT array_agg(column_name ORDER BY other_column) FROM table_name; +-----------------------------------------------+ diff --git a/datafusion/functions-aggregate/src/average.rs b/datafusion/functions-aggregate/src/average.rs index 12d98a041fb1..3fa58f3c2082 100644 --- a/datafusion/functions-aggregate/src/average.rs +++ b/datafusion/functions-aggregate/src/average.rs @@ -248,14 +248,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_avg_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Returns the average of numeric values in the specified column.", - ) - .with_syntax_example("avg(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the average of numeric values in the specified column.", + "avg(expression)", + ) + .with_sql_example( + r#"```sql > SELECT avg(column_name) FROM table_name; +---------------------------+ | avg(column_name) | @@ -263,9 +262,9 @@ fn get_avg_doc() -> &'static Documentation { | 42.75 | +---------------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } diff --git a/datafusion/functions-aggregate/src/bit_and_or_xor.rs b/datafusion/functions-aggregate/src/bit_and_or_xor.rs index 8b5da2e3b162..aeed78737c1d 100644 --- a/datafusion/functions-aggregate/src/bit_and_or_xor.rs +++ b/datafusion/functions-aggregate/src/bit_and_or_xor.rs @@ -139,12 +139,13 @@ static BIT_AND_DOC: OnceLock = OnceLock::new(); fn get_bit_and_doc() -> &'static Documentation { BIT_AND_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description("Computes the bitwise AND of all non-null input values.") - .with_syntax_example("bit_and(expression)") - .with_standard_argument("expression", Some("Integer")) - .build() + Documentation::builder( + DOC_SECTION_GENERAL, + "Computes the bitwise AND of all non-null input values.", + "bit_and(expression)", + ) + .with_standard_argument("expression", Some("Integer")) + .build() }) } @@ -152,12 +153,13 @@ static BIT_OR_DOC: OnceLock = OnceLock::new(); fn get_bit_or_doc() -> &'static Documentation { BIT_OR_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description("Computes the bitwise OR of all non-null input values.") - .with_syntax_example("bit_or(expression)") - .with_standard_argument("expression", Some("Integer")) - .build() + Documentation::builder( + DOC_SECTION_GENERAL, + "Computes the bitwise OR of all non-null input values.", + "bit_or(expression)", + ) + .with_standard_argument("expression", Some("Integer")) + .build() }) } @@ -165,14 +167,13 @@ static BIT_XOR_DOC: OnceLock = OnceLock::new(); fn get_bit_xor_doc() -> &'static Documentation { BIT_XOR_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Computes the bitwise exclusive OR of all non-null input values.", - ) - .with_syntax_example("bit_xor(expression)") - .with_standard_argument("expression", Some("Integer")) - .build() + Documentation::builder( + DOC_SECTION_GENERAL, + "Computes the bitwise exclusive OR of all non-null input values.", + "bit_xor(expression)", + ) + .with_standard_argument("expression", Some("Integer")) + .build() }) } diff --git a/datafusion/functions-aggregate/src/bool_and_or.rs b/datafusion/functions-aggregate/src/bool_and_or.rs index 55f5aa988495..df9271d8160a 100644 --- a/datafusion/functions-aggregate/src/bool_and_or.rs +++ b/datafusion/functions-aggregate/src/bool_and_or.rs @@ -186,14 +186,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_bool_and_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Returns true if all non-null input values are true, otherwise false.", - ) - .with_syntax_example("bool_and(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns true if all non-null input values are true, otherwise false.", + "bool_and(expression)", + ) + .with_sql_example( + r#"```sql > SELECT bool_and(column_name) FROM table_name; +----------------------------+ | bool_and(column_name) | @@ -201,9 +200,9 @@ fn get_bool_and_doc() -> &'static Documentation { | true | +----------------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } @@ -334,14 +333,13 @@ impl AggregateUDFImpl for BoolOr { fn get_bool_or_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Returns true if any non-null input value is true, otherwise false.", - ) - .with_syntax_example("bool_or(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns true if any non-null input value is true, otherwise false.", + "bool_or(expression)", + ) + .with_sql_example( + r#"```sql > SELECT bool_or(column_name) FROM table_name; +----------------------------+ | bool_or(column_name) | @@ -349,9 +347,9 @@ fn get_bool_or_doc() -> &'static Documentation { | true | +----------------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } diff --git a/datafusion/functions-aggregate/src/correlation.rs b/datafusion/functions-aggregate/src/correlation.rs index 14124ce46aea..4711b4240797 100644 --- a/datafusion/functions-aggregate/src/correlation.rs +++ b/datafusion/functions-aggregate/src/correlation.rs @@ -119,14 +119,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_corr_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( - "Returns the coefficient of correlation between two numeric values.", - ) - .with_syntax_example("corr(expression1, expression2)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STATISTICAL, + "Returns the coefficient of correlation between two numeric values.", + "corr(expression1, expression2)", + ) + .with_sql_example( + r#"```sql > SELECT corr(column1, column2) FROM table_name; +--------------------------------+ | corr(column1, column2) | @@ -134,10 +133,10 @@ fn get_corr_doc() -> &'static Documentation { | 0.85 | +--------------------------------+ ```"#, - ) - .with_standard_argument("expression1", Some("First")) - .with_standard_argument("expression2", Some("Second")) - .build() + ) + .with_standard_argument("expression1", Some("First")) + .with_standard_argument("expression2", Some("Second")) + .build() }) } diff --git a/datafusion/functions-aggregate/src/count.rs b/datafusion/functions-aggregate/src/count.rs index 4b1ab323b8f4..c8f8c8153ce1 100644 --- a/datafusion/functions-aggregate/src/count.rs +++ b/datafusion/functions-aggregate/src/count.rs @@ -336,12 +336,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_count_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( + Documentation::builder( + DOC_SECTION_GENERAL, "Returns the number of non-null values in the specified column. To include null values in the total count, use `count(*)`.", - ) - .with_syntax_example("count(expression)") + + "count(expression)") .with_sql_example(r#"```sql > SELECT count(column_name) FROM table_name; +-----------------------+ diff --git a/datafusion/functions-aggregate/src/covariance.rs b/datafusion/functions-aggregate/src/covariance.rs index 94727fddd9f8..0c29589e9095 100644 --- a/datafusion/functions-aggregate/src/covariance.rs +++ b/datafusion/functions-aggregate/src/covariance.rs @@ -137,12 +137,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_covar_samp_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description("Returns the sample covariance of a set of number pairs.") - .with_syntax_example("covar_samp(expression1, expression2)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STATISTICAL, + "Returns the sample covariance of a set of number pairs.", + "covar_samp(expression1, expression2)", + ) + .with_sql_example( + r#"```sql > SELECT covar_samp(column1, column2) FROM table_name; +-----------------------------------+ | covar_samp(column1, column2) | @@ -150,10 +151,10 @@ fn get_covar_samp_doc() -> &'static Documentation { | 8.25 | +-----------------------------------+ ```"#, - ) - .with_standard_argument("expression1", Some("First")) - .with_standard_argument("expression2", Some("Second")) - .build() + ) + .with_standard_argument("expression1", Some("First")) + .with_standard_argument("expression2", Some("Second")) + .build() }) } @@ -232,14 +233,13 @@ impl AggregateUDFImpl for CovariancePopulation { fn get_covar_pop_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( - "Returns the population covariance of a set of number pairs.", - ) - .with_syntax_example("covar_pop(expression1, expression2)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STATISTICAL, + "Returns the population covariance of a set of number pairs.", + "covar_pop(expression1, expression2)", + ) + .with_sql_example( + r#"```sql > SELECT covar_pop(column1, column2) FROM table_name; +-----------------------------------+ | covar_pop(column1, column2) | @@ -247,10 +247,10 @@ fn get_covar_pop_doc() -> &'static Documentation { | 7.63 | +-----------------------------------+ ```"#, - ) - .with_standard_argument("expression1", Some("First")) - .with_standard_argument("expression2", Some("Second")) - .build() + ) + .with_standard_argument("expression1", Some("First")) + .with_standard_argument("expression2", Some("Second")) + .build() }) } diff --git a/datafusion/functions-aggregate/src/first_last.rs b/datafusion/functions-aggregate/src/first_last.rs index a20330a7aaf5..b7001f52ac84 100644 --- a/datafusion/functions-aggregate/src/first_last.rs +++ b/datafusion/functions-aggregate/src/first_last.rs @@ -169,12 +169,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_first_value_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( + Documentation::builder( + DOC_SECTION_GENERAL, "Returns the first element in an aggregation group according to the requested ordering. If no ordering is given, returns an arbitrary element from the group.", - ) - .with_syntax_example("first_value(expression [ORDER BY expression])") + + "first_value(expression [ORDER BY expression])") .with_sql_example(r#"```sql > SELECT first_value(column_name ORDER BY other_column) FROM table_name; +-----------------------------------------------+ @@ -490,12 +489,11 @@ impl AggregateUDFImpl for LastValue { fn get_last_value_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( + Documentation::builder( + DOC_SECTION_GENERAL, "Returns the last element in an aggregation group according to the requested ordering. If no ordering is given, returns an arbitrary element from the group.", - ) - .with_syntax_example("last_value(expression [ORDER BY expression])") + + "last_value(expression [ORDER BY expression])") .with_sql_example(r#"```sql > SELECT last_value(column_name ORDER BY other_column) FROM table_name; +-----------------------------------------------+ diff --git a/datafusion/functions-aggregate/src/grouping.rs b/datafusion/functions-aggregate/src/grouping.rs index 88275193d773..4a45890b0e70 100644 --- a/datafusion/functions-aggregate/src/grouping.rs +++ b/datafusion/functions-aggregate/src/grouping.rs @@ -108,12 +108,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_grouping_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( + Documentation::builder( + DOC_SECTION_GENERAL, "Returns 1 if the data is aggregated across the specified column, or 0 if it is not aggregated in the result set.", - ) - .with_syntax_example("grouping(expression)") + + "grouping(expression)") .with_sql_example(r#"```sql > SELECT column_name, GROUPING(column_name) AS group_column FROM table_name diff --git a/datafusion/functions-aggregate/src/median.rs b/datafusion/functions-aggregate/src/median.rs index 7e0b52a2f857..5b8792298533 100644 --- a/datafusion/functions-aggregate/src/median.rs +++ b/datafusion/functions-aggregate/src/median.rs @@ -163,12 +163,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_median_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description("Returns the median value in the specified column.") - .with_syntax_example("median(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the median value in the specified column.", + "median(expression)", + ) + .with_sql_example( + r#"```sql > SELECT median(column_name) FROM table_name; +----------------------+ | median(column_name) | @@ -176,9 +177,9 @@ fn get_median_doc() -> &'static Documentation { | 45.5 | +----------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } diff --git a/datafusion/functions-aggregate/src/min_max.rs b/datafusion/functions-aggregate/src/min_max.rs index 49b528c2f41c..2077f1567411 100644 --- a/datafusion/functions-aggregate/src/min_max.rs +++ b/datafusion/functions-aggregate/src/min_max.rs @@ -354,12 +354,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_max_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description("Returns the maximum value in the specified column.") - .with_syntax_example("max(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the maximum value in the specified column.", + "max(expression)", + ) + .with_sql_example( + r#"```sql > SELECT max(column_name) FROM table_name; +----------------------+ | max(column_name) | @@ -367,9 +368,9 @@ fn get_max_doc() -> &'static Documentation { | 150 | +----------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } @@ -1183,12 +1184,13 @@ impl AggregateUDFImpl for Min { fn get_min_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description("Returns the minimum value in the specified column.") - .with_syntax_example("min(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the minimum value in the specified column.", + "min(expression)", + ) + .with_sql_example( + r#"```sql > SELECT min(column_name) FROM table_name; +----------------------+ | min(column_name) | @@ -1196,9 +1198,9 @@ fn get_min_doc() -> &'static Documentation { | 12 | +----------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } diff --git a/datafusion/functions-aggregate/src/nth_value.rs b/datafusion/functions-aggregate/src/nth_value.rs index 8a8010ef27bd..0c72939633b1 100644 --- a/datafusion/functions-aggregate/src/nth_value.rs +++ b/datafusion/functions-aggregate/src/nth_value.rs @@ -173,12 +173,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_nth_value_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Returns the nth value in a group of values.", - ) - .with_syntax_example("nth_value(expression, n ORDER BY expression)") + + "nth_value(expression, n ORDER BY expression)") .with_sql_example(r#"```sql > SELECT dept_id, salary, NTH_VALUE(salary, 2) OVER (PARTITION BY dept_id ORDER BY salary ASC) AS second_salary_by_dept FROM employee; diff --git a/datafusion/functions-aggregate/src/regr.rs b/datafusion/functions-aggregate/src/regr.rs index dca309dfe101..f302b72f94b5 100644 --- a/datafusion/functions-aggregate/src/regr.rs +++ b/datafusion/functions-aggregate/src/regr.rs @@ -138,13 +138,12 @@ fn get_regr_docs() -> &'static HashMap { let mut hash_map = HashMap::new(); hash_map.insert( RegrType::Slope, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Returns the slope of the linear regression line for non-null pairs in aggregate columns. \ Given input column Y and X: regr_slope(Y, X) returns the slope (k in Y = k*X + b) using minimal RSS fitting.", - ) - .with_syntax_example("regr_slope(expression_y, expression_x)") + + "regr_slope(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -152,13 +151,12 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::Intercept, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the y-intercept of the linear regression line. For the equation (y = kx + b), \ this function returns b.", - ) - .with_syntax_example("regr_intercept(expression_y, expression_x)") + + "regr_intercept(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -166,12 +164,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::Count, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Counts the number of non-null paired data points.", - ) - .with_syntax_example("regr_count(expression_y, expression_x)") + + "regr_count(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -179,12 +176,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::R2, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the square of the correlation coefficient between the independent and dependent variables.", - ) - .with_syntax_example("regr_r2(expression_y, expression_x)") + + "regr_r2(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -192,12 +188,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::AvgX, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the average of the independent variable (input) expression_x for the non-null paired data points.", - ) - .with_syntax_example("regr_avgx(expression_y, expression_x)") + + "regr_avgx(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -205,12 +200,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::AvgY, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the average of the dependent variable (output) expression_y for the non-null paired data points.", - ) - .with_syntax_example("regr_avgy(expression_y, expression_x)") + + "regr_avgy(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -218,12 +212,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::SXX, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the sum of squares of the independent variable.", - ) - .with_syntax_example("regr_sxx(expression_y, expression_x)") + + "regr_sxx(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -231,12 +224,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::SYY, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the sum of squares of the dependent variable.", - ) - .with_syntax_example("regr_syy(expression_y, expression_x)") + + "regr_syy(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() @@ -244,12 +236,11 @@ fn get_regr_docs() -> &'static HashMap { hash_map.insert( RegrType::SXY, - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( + Documentation::builder( + DOC_SECTION_STATISTICAL, "Computes the sum of products of paired data points.", - ) - .with_syntax_example("regr_sxy(expression_y, expression_x)") + + "regr_sxy(expression_y, expression_x)") .with_standard_argument("expression_y", Some("Dependent variable")) .with_standard_argument("expression_x", Some("Independent variable")) .build() diff --git a/datafusion/functions-aggregate/src/stddev.rs b/datafusion/functions-aggregate/src/stddev.rs index 3e1038f8ce28..afc9bf6255c2 100644 --- a/datafusion/functions-aggregate/src/stddev.rs +++ b/datafusion/functions-aggregate/src/stddev.rs @@ -142,12 +142,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_stddev_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description("Returns the standard deviation of a set of numbers.") - .with_syntax_example("stddev(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STATISTICAL, + "Returns the standard deviation of a set of numbers.", + "stddev(expression)", + ) + .with_sql_example( + r#"```sql > SELECT stddev(column_name) FROM table_name; +----------------------+ | stddev(column_name) | @@ -155,9 +156,9 @@ fn get_stddev_doc() -> &'static Documentation { | 12.34 | +----------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } @@ -263,14 +264,13 @@ impl AggregateUDFImpl for StddevPop { fn get_stddev_pop_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STATISTICAL) - .with_description( - "Returns the population standard deviation of a set of numbers.", - ) - .with_syntax_example("stddev_pop(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STATISTICAL, + "Returns the population standard deviation of a set of numbers.", + "stddev_pop(expression)", + ) + .with_sql_example( + r#"```sql > SELECT stddev_pop(column_name) FROM table_name; +--------------------------+ | stddev_pop(column_name) | @@ -278,9 +278,9 @@ fn get_stddev_pop_doc() -> &'static Documentation { | 10.56 | +--------------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } diff --git a/datafusion/functions-aggregate/src/string_agg.rs b/datafusion/functions-aggregate/src/string_agg.rs index 18cf6a15988d..4fd2d91b46c0 100644 --- a/datafusion/functions-aggregate/src/string_agg.rs +++ b/datafusion/functions-aggregate/src/string_agg.rs @@ -111,12 +111,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_string_agg_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Concatenates the values of string expressions and places separator values between them." - ) - .with_syntax_example("string_agg(expression, delimiter)") + Documentation::builder( + DOC_SECTION_GENERAL, + "Concatenates the values of string expressions and places separator values between them.", + + "string_agg(expression, delimiter)") .with_sql_example(r#"```sql > SELECT string_agg(name, ', ') AS names_list FROM employee; diff --git a/datafusion/functions-aggregate/src/sum.rs b/datafusion/functions-aggregate/src/sum.rs index 6c438e10ea66..447b5d8a57c4 100644 --- a/datafusion/functions-aggregate/src/sum.rs +++ b/datafusion/functions-aggregate/src/sum.rs @@ -247,12 +247,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_sum_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description("Returns the sum of all values in the specified column.") - .with_syntax_example("sum(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the sum of all values in the specified column.", + "sum(expression)", + ) + .with_sql_example( + r#"```sql > SELECT sum(column_name) FROM table_name; +-----------------------+ | sum(column_name) | @@ -260,9 +261,9 @@ fn get_sum_doc() -> &'static Documentation { | 12345 | +-----------------------+ ```"#, - ) - .with_standard_argument("expression", None) - .build() + ) + .with_standard_argument("expression", None) + .build() }) } diff --git a/datafusion/functions-aggregate/src/variance.rs b/datafusion/functions-aggregate/src/variance.rs index bb518bf76b6a..9c99a9138dd5 100644 --- a/datafusion/functions-aggregate/src/variance.rs +++ b/datafusion/functions-aggregate/src/variance.rs @@ -145,14 +145,13 @@ static VARIANCE_SAMPLE_DOC: OnceLock = OnceLock::new(); fn get_variance_sample_doc() -> &'static Documentation { VARIANCE_SAMPLE_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Returns the statistical sample variance of a set of numbers.", - ) - .with_syntax_example("var(expression)") - .with_standard_argument("expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the statistical sample variance of a set of numbers.", + "var(expression)", + ) + .with_standard_argument("expression", Some("Numeric")) + .build() }) } @@ -250,14 +249,13 @@ static VARIANCE_POPULATION_DOC: OnceLock = OnceLock::new(); fn get_variance_population_doc() -> &'static Documentation { VARIANCE_POPULATION_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_GENERAL) - .with_description( - "Returns the statistical population variance of a set of numbers.", - ) - .with_syntax_example("var_pop(expression)") - .with_standard_argument("expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_GENERAL, + "Returns the statistical population variance of a set of numbers.", + "var_pop(expression)", + ) + .with_standard_argument("expression", Some("Numeric")) + .build() }) } diff --git a/datafusion/functions-nested/src/array_has.rs b/datafusion/functions-nested/src/array_has.rs index ec9f263f6dd4..c71314d8263f 100644 --- a/datafusion/functions-nested/src/array_has.rs +++ b/datafusion/functions-nested/src/array_has.rs @@ -146,12 +146,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_has_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns true if the array contains the element.", - ) - .with_syntax_example("array_has(array, element)") + + "array_has(array, element)") .with_sql_example( r#"```sql > select array_has([1, 2, 3], 2); @@ -344,12 +343,11 @@ impl ScalarUDFImpl for ArrayHasAll { fn get_array_has_all_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns true if all elements of sub-array exist in array.", - ) - .with_syntax_example("array_has_all(array, sub-array)") + + "array_has_all(array, sub-array)") .with_sql_example( r#"```sql > select array_has_all([1, 2, 3, 4], [2, 3]); @@ -428,12 +426,11 @@ impl ScalarUDFImpl for ArrayHasAny { fn get_array_has_any_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns true if any elements exist in both arrays.", - ) - .with_syntax_example("array_has_any(array, sub-array)") + + "array_has_any(array, sub-array)") .with_sql_example( r#"```sql > select array_has_any([1, 2, 3], [3, 4]); diff --git a/datafusion/functions-nested/src/cardinality.rs b/datafusion/functions-nested/src/cardinality.rs index 66fa587f021a..45543d1bd68b 100644 --- a/datafusion/functions-nested/src/cardinality.rs +++ b/datafusion/functions-nested/src/cardinality.rs @@ -104,12 +104,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_cardinality_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the total number of elements in the array.", - ) - .with_syntax_example("cardinality(array)") + + "cardinality(array)") .with_sql_example( r#"```sql > select cardinality([[1, 2, 3, 4], [5, 6, 7, 8]]); diff --git a/datafusion/functions-nested/src/concat.rs b/datafusion/functions-nested/src/concat.rs index a103c1474bb1..0b7056858d7e 100644 --- a/datafusion/functions-nested/src/concat.rs +++ b/datafusion/functions-nested/src/concat.rs @@ -107,12 +107,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_append_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Appends an element to the end of an array.", - ) - .with_syntax_example("array_append(array, element)") + + "array_append(array, element)") .with_sql_example( r#"```sql > select array_append([1, 2, 3], 4); @@ -206,12 +205,11 @@ static DOCUMENTATION_PREPEND: OnceLock = OnceLock::new(); fn get_array_prepend_doc() -> &'static Documentation { DOCUMENTATION_PREPEND.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Prepends an element to the beginning of an array.", - ) - .with_syntax_example("array_prepend(element, array)") + + "array_prepend(element, array)") .with_sql_example( r#"```sql > select array_prepend(1, [2, 3, 4]); @@ -327,12 +325,11 @@ impl ScalarUDFImpl for ArrayConcat { fn get_array_concat_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Concatenates arrays.", - ) - .with_syntax_example("array_concat(array[, ..., array_n])") + + "array_concat(array[, ..., array_n])") .with_sql_example( r#"```sql > select array_concat([1, 2], [3, 4], [5, 6]); diff --git a/datafusion/functions-nested/src/dimension.rs b/datafusion/functions-nested/src/dimension.rs index 24822b89a662..9ca7c87aba55 100644 --- a/datafusion/functions-nested/src/dimension.rs +++ b/datafusion/functions-nested/src/dimension.rs @@ -102,12 +102,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_dims_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an array of the array's dimensions.", - ) - .with_syntax_example("array_dims(array)") + + "array_dims(array)") .with_sql_example( r#"```sql > select array_dims([[1, 2, 3], [4, 5, 6]]); @@ -188,12 +187,11 @@ impl ScalarUDFImpl for ArrayNdims { fn get_array_ndims_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the number of dimensions of the array.", - ) - .with_syntax_example("array_ndims(array, element)") + + "array_ndims(array, element)") .with_sql_example( r#"```sql > select array_ndims([[1, 2, 3], [4, 5, 6]]); diff --git a/datafusion/functions-nested/src/distance.rs b/datafusion/functions-nested/src/distance.rs index 4f7bba88332e..381ddeb59a0b 100644 --- a/datafusion/functions-nested/src/distance.rs +++ b/datafusion/functions-nested/src/distance.rs @@ -117,12 +117,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_distance_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the Euclidean distance between two input arrays of equal length.", - ) - .with_syntax_example("array_distance(array1, array2)") + + "array_distance(array1, array2)") .with_sql_example( r#"```sql > select array_distance([1, 2], [1, 4]); diff --git a/datafusion/functions-nested/src/empty.rs b/datafusion/functions-nested/src/empty.rs index bf80679c6215..5270c84c0338 100644 --- a/datafusion/functions-nested/src/empty.rs +++ b/datafusion/functions-nested/src/empty.rs @@ -94,12 +94,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_empty_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns 1 for an empty array or 0 for a non-empty array.", - ) - .with_syntax_example("empty(array)") + + "empty(array)") .with_sql_example( r#"```sql > select empty([1]); diff --git a/datafusion/functions-nested/src/except.rs b/datafusion/functions-nested/src/except.rs index 89ff6a66cad0..83c09ad7fd90 100644 --- a/datafusion/functions-nested/src/except.rs +++ b/datafusion/functions-nested/src/except.rs @@ -94,12 +94,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_except_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an array of the elements that appear in the first array but not in the second.", - ) - .with_syntax_example("array_except(array1, array2)") + + "array_except(array1, array2)") .with_sql_example( r#"```sql > select array_except([1, 2, 3, 4], [5, 6, 3, 4]); diff --git a/datafusion/functions-nested/src/extract.rs b/datafusion/functions-nested/src/extract.rs index bb78eab0c44b..13095bc4ba3f 100644 --- a/datafusion/functions-nested/src/extract.rs +++ b/datafusion/functions-nested/src/extract.rs @@ -164,12 +164,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_element_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Extracts the element with the index n from the array.", - ) - .with_syntax_example("array_element(array, index)") + + "array_element(array, index)") .with_sql_example( r#"```sql > select array_element([1, 2, 3, 4], 3); @@ -369,12 +368,11 @@ impl ScalarUDFImpl for ArraySlice { fn get_array_slice_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns a slice of the array based on 1-indexed start and end positions.", - ) - .with_syntax_example("array_slice(array, begin, end)") + + "array_slice(array, begin, end)") .with_sql_example( r#"```sql > select array_slice([1, 2, 3, 4, 5, 6, 7, 8], 3, 6); @@ -681,12 +679,11 @@ impl ScalarUDFImpl for ArrayPopFront { fn get_array_pop_front_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the array without the first element.", - ) - .with_syntax_example("array_pop_front(array)") + + "array_pop_front(array)") .with_sql_example( r#"```sql > select array_pop_front([1, 2, 3]); @@ -790,12 +787,11 @@ impl ScalarUDFImpl for ArrayPopBack { fn get_array_pop_back_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the array without the last element.", - ) - .with_syntax_example("array_pop_back(array)") + + "array_pop_back(array)") .with_sql_example( r#"```sql > select array_pop_back([1, 2, 3]); @@ -907,12 +903,11 @@ impl ScalarUDFImpl for ArrayAnyValue { fn get_array_any_value_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the first non-null element in the array.", - ) - .with_syntax_example("array_any_value(array)") + + "array_any_value(array)") .with_sql_example( r#"```sql > select array_any_value([NULL, 1, 2, 3]); diff --git a/datafusion/functions-nested/src/flatten.rs b/datafusion/functions-nested/src/flatten.rs index b39d3b2b2b9b..3650b1f37b1b 100644 --- a/datafusion/functions-nested/src/flatten.rs +++ b/datafusion/functions-nested/src/flatten.rs @@ -111,12 +111,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_flatten_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Converts an array of arrays to a flat array.\n\n- Applies to any depth of nested arrays\n- Does not change arrays that are already flat\n\nThe flattened array contains all the elements from all source arrays.", - ) - .with_syntax_example("flatten(array)") + + "flatten(array)") .with_sql_example( r#"```sql > select flatten([[1, 2], [3, 4]]); diff --git a/datafusion/functions-nested/src/length.rs b/datafusion/functions-nested/src/length.rs index 78d66ad733ff..084b37bf13a4 100644 --- a/datafusion/functions-nested/src/length.rs +++ b/datafusion/functions-nested/src/length.rs @@ -98,12 +98,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_length_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the length of the array dimension.", - ) - .with_syntax_example("array_length(array, dimension)") + + "array_length(array, dimension)") .with_sql_example( r#"```sql > select array_length([1, 2, 3, 4, 5], 1); diff --git a/datafusion/functions-nested/src/make_array.rs b/datafusion/functions-nested/src/make_array.rs index a98b88b065c5..825824a82d20 100644 --- a/datafusion/functions-nested/src/make_array.rs +++ b/datafusion/functions-nested/src/make_array.rs @@ -147,12 +147,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_make_array_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an array using the specified input expressions.", - ) - .with_syntax_example("make_array(expression1[, ..., expression_n])") + + "make_array(expression1[, ..., expression_n])") .with_sql_example( r#"```sql > select make_array(1, 2, 3, 4, 5); diff --git a/datafusion/functions-nested/src/map.rs b/datafusion/functions-nested/src/map.rs index ec63d36a47b7..e49391379817 100644 --- a/datafusion/functions-nested/src/map.rs +++ b/datafusion/functions-nested/src/map.rs @@ -255,13 +255,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_map_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MAP) - .with_description( + Documentation::builder( + DOC_SECTION_MAP, "Returns an Arrow map with the specified key-value pairs.\n\n\ - The `make_map` function creates a map from two lists: one for keys and one for values. Each key must be unique and non-null." - ) - .with_syntax_example( + The `make_map` function creates a map from two lists: one for keys and one for values. Each key must be unique and non-null.", + "map(key, value)\nmap(key: value)\nmake_map(['key1', 'key2'], ['value1', 'value2'])" ) .with_sql_example( diff --git a/datafusion/functions-nested/src/map_extract.rs b/datafusion/functions-nested/src/map_extract.rs index eda534348b95..d2ab078cb22d 100644 --- a/datafusion/functions-nested/src/map_extract.rs +++ b/datafusion/functions-nested/src/map_extract.rs @@ -118,12 +118,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_map_extract_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MAP) - .with_description( + Documentation::builder( + DOC_SECTION_MAP, "Returns a list containing the value for the given key or an empty list if the key is not present in the map.", - ) - .with_syntax_example("map_extract(map, key)") + "map_extract(map, key)") .with_sql_example( r#"```sql SELECT map_extract(MAP {'a': 1, 'b': NULL, 'c': 3}, 'a'); diff --git a/datafusion/functions-nested/src/map_keys.rs b/datafusion/functions-nested/src/map_keys.rs index 86d0aecf29f0..4abdbcad1e82 100644 --- a/datafusion/functions-nested/src/map_keys.rs +++ b/datafusion/functions-nested/src/map_keys.rs @@ -96,12 +96,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_map_keys_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MAP) - .with_description( - "Returns a list of all keys in the map." - ) - .with_syntax_example("map_keys(map)") + Documentation::builder( + DOC_SECTION_MAP, + "Returns a list of all keys in the map.", + "map_keys(map)") .with_sql_example( r#"```sql SELECT map_keys(MAP {'a': 1, 'b': NULL, 'c': 3}); diff --git a/datafusion/functions-nested/src/map_values.rs b/datafusion/functions-nested/src/map_values.rs index d8d64a34c6e0..f1cc36cade63 100644 --- a/datafusion/functions-nested/src/map_values.rs +++ b/datafusion/functions-nested/src/map_values.rs @@ -96,12 +96,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_map_values_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MAP) - .with_description( - "Returns a list of all values in the map." - ) - .with_syntax_example("map_values(map)") + Documentation::builder( + DOC_SECTION_MAP, + "Returns a list of all values in the map.", + + "map_values(map)") .with_sql_example( r#"```sql SELECT map_values(MAP {'a': 1, 'b': NULL, 'c': 3}); diff --git a/datafusion/functions-nested/src/position.rs b/datafusion/functions-nested/src/position.rs index 54e93c301f6c..9ed4b4c42d14 100644 --- a/datafusion/functions-nested/src/position.rs +++ b/datafusion/functions-nested/src/position.rs @@ -103,12 +103,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_position_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the position of the first occurrence of the specified element in the array.", - ) - .with_syntax_example("array_position(array, element)\narray_position(array, element, index)") + + "array_position(array, element)\narray_position(array, element, index)") .with_sql_example( r#"```sql > select array_position([1, 2, 2, 3, 1, 4], 2); @@ -275,12 +274,11 @@ impl ScalarUDFImpl for ArrayPositions { fn get_array_positions_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Searches for an element in the array, returns all occurrences.", - ) - .with_syntax_example("array_positions(array, element)") + + "array_positions(array, element)") .with_sql_example( r#"```sql > select array_positions([1, 2, 2, 3, 1, 4], 2); diff --git a/datafusion/functions-nested/src/range.rs b/datafusion/functions-nested/src/range.rs index bb6373f383fe..360f0023dc47 100644 --- a/datafusion/functions-nested/src/range.rs +++ b/datafusion/functions-nested/src/range.rs @@ -150,12 +150,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_range_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an Arrow array between start and stop with step. The range start..end contains all values with start <= x < end. It is empty if start >= end. Step cannot be 0.", - ) - .with_syntax_example("range(start, stop, step)") + + "range(start, stop, step)") .with_sql_example( r#"```sql > select range(2, 10, 3); @@ -294,12 +293,11 @@ static GENERATE_SERIES_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_generate_series_doc() -> &'static Documentation { GENERATE_SERIES_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Similar to the range function, but it includes the upper bound.", - ) - .with_syntax_example("generate_series(start, stop, step)") + + "generate_series(start, stop, step)") .with_sql_example( r#"```sql > select generate_series(1,3); diff --git a/datafusion/functions-nested/src/remove.rs b/datafusion/functions-nested/src/remove.rs index 42171adc987e..df0edc99bc62 100644 --- a/datafusion/functions-nested/src/remove.rs +++ b/datafusion/functions-nested/src/remove.rs @@ -95,12 +95,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_remove_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Removes the first element from the array equal to the given value.", - ) - .with_syntax_example("array_remove(array, element)") + + "array_remove(array, element)") .with_sql_example( r#"```sql > select array_remove([1, 2, 2, 3, 2, 1, 4], 2); @@ -182,12 +181,11 @@ impl ScalarUDFImpl for ArrayRemoveN { fn get_array_remove_n_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Removes the first `max` elements from the array equal to the given value.", - ) - .with_syntax_example("array_remove_n(array, element, max)") + + "array_remove_n(array, element, max)") .with_sql_example( r#"```sql > select array_remove_n([1, 2, 2, 3, 2, 1, 4], 2, 2); @@ -273,12 +271,11 @@ impl ScalarUDFImpl for ArrayRemoveAll { fn get_array_remove_all_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Removes all elements from the array equal to the given value.", - ) - .with_syntax_example("array_remove_all(array, element)") + + "array_remove_all(array, element)") .with_sql_example( r#"```sql > select array_remove_all([1, 2, 2, 3, 2, 1, 4], 2); diff --git a/datafusion/functions-nested/src/repeat.rs b/datafusion/functions-nested/src/repeat.rs index e08b588b119f..f67ab83b1d39 100644 --- a/datafusion/functions-nested/src/repeat.rs +++ b/datafusion/functions-nested/src/repeat.rs @@ -100,12 +100,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_repeat_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an array containing element `count` times.", - ) - .with_syntax_example("array_repeat(element, count)") + + "array_repeat(element, count)") .with_sql_example( r#"```sql > select array_repeat(1, 3); diff --git a/datafusion/functions-nested/src/replace.rs b/datafusion/functions-nested/src/replace.rs index 3dd67a8e105a..01811b77734d 100644 --- a/datafusion/functions-nested/src/replace.rs +++ b/datafusion/functions-nested/src/replace.rs @@ -111,12 +111,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_replace_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Replaces the first occurrence of the specified element with another specified element.", - ) - .with_syntax_example("array_replace(array, from, to)") + + "array_replace(array, from, to)") .with_sql_example( r#"```sql > select array_replace([1, 2, 2, 3, 2, 1, 4], 2, 5); @@ -194,12 +193,11 @@ impl ScalarUDFImpl for ArrayReplaceN { fn get_array_replace_n_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Replaces the first `max` occurrences of the specified element with another specified element.", - ) - .with_syntax_example("array_replace_n(array, from, to, max)") + + "array_replace_n(array, from, to, max)") .with_sql_example( r#"```sql > select array_replace_n([1, 2, 2, 3, 2, 1, 4], 2, 5, 2); @@ -281,12 +279,11 @@ impl ScalarUDFImpl for ArrayReplaceAll { fn get_array_replace_all_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Replaces all occurrences of the specified element with another specified element.", - ) - .with_syntax_example("array_replace_all(array, from, to)") + + "array_replace_all(array, from, to)") .with_sql_example( r#"```sql > select array_replace_all([1, 2, 2, 3, 2, 1, 4], 2, 5); diff --git a/datafusion/functions-nested/src/resize.rs b/datafusion/functions-nested/src/resize.rs index 1bb87d573e4e..c9487dd81843 100644 --- a/datafusion/functions-nested/src/resize.rs +++ b/datafusion/functions-nested/src/resize.rs @@ -101,12 +101,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_resize_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Resizes the list to contain size elements. Initializes new elements with value or empty if value is not set.", - ) - .with_syntax_example("array_resize(array, size, value)") + + "array_resize(array, size, value)") .with_sql_example( r#"```sql > select array_resize([1, 2, 3], 5, 0); diff --git a/datafusion/functions-nested/src/reverse.rs b/datafusion/functions-nested/src/reverse.rs index 0f2d2852377c..aa898268d10b 100644 --- a/datafusion/functions-nested/src/reverse.rs +++ b/datafusion/functions-nested/src/reverse.rs @@ -93,12 +93,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_reverse_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns the array with the order of the elements reversed.", - ) - .with_syntax_example("array_reverse(array)") + + "array_reverse(array)") .with_sql_example( r#"```sql > select array_reverse([1, 2, 3, 4]); diff --git a/datafusion/functions-nested/src/set_ops.rs b/datafusion/functions-nested/src/set_ops.rs index 48f5862f1702..889eaed4edcc 100644 --- a/datafusion/functions-nested/src/set_ops.rs +++ b/datafusion/functions-nested/src/set_ops.rs @@ -119,12 +119,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_union_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an array of elements that are present in both arrays (all elements from both arrays) with out duplicates.", - ) - .with_syntax_example("array_union(array1, array2)") + + "array_union(array1, array2)") .with_sql_example( r#"```sql > select array_union([1, 2, 3, 4], [5, 6, 3, 4]); @@ -208,12 +207,11 @@ impl ScalarUDFImpl for ArrayIntersect { fn get_array_intersect_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns an array of elements in the intersection of array1 and array2.", - ) - .with_syntax_example("array_intersect(array1, array2)") + + "array_intersect(array1, array2)") .with_sql_example( r#"```sql > select array_intersect([1, 2, 3, 4], [5, 6, 3, 4]); @@ -307,12 +305,11 @@ impl ScalarUDFImpl for ArrayDistinct { fn get_array_distinct_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Returns distinct values from the array after removing duplicates.", - ) - .with_syntax_example("array_distinct(array)") + + "array_distinct(array)") .with_sql_example( r#"```sql > select array_distinct([1, 3, 2, 3, 1, 2, 4]); diff --git a/datafusion/functions-nested/src/sort.rs b/datafusion/functions-nested/src/sort.rs index 3d54826a7ca0..cdd6842acc0e 100644 --- a/datafusion/functions-nested/src/sort.rs +++ b/datafusion/functions-nested/src/sort.rs @@ -107,12 +107,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_array_sort_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Sort array.", - ) - .with_syntax_example("array_sort(array, desc, nulls_first)") + + "array_sort(array, desc, nulls_first)") .with_sql_example( r#"```sql > select array_sort([3, 1, 2]); diff --git a/datafusion/functions-nested/src/string.rs b/datafusion/functions-nested/src/string.rs index cacc0dcc6589..8c6cb73e97c9 100644 --- a/datafusion/functions-nested/src/string.rs +++ b/datafusion/functions-nested/src/string.rs @@ -180,12 +180,11 @@ static DOCUMENTATION_ARRAY_TO_STRING: OnceLock = OnceLock::new(); fn get_array_to_string_doc() -> &'static Documentation { DOCUMENTATION_ARRAY_TO_STRING.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Converts each element to its text representation.", - ) - .with_syntax_example("array_to_string(array, delimiter[, null_string])") + + "array_to_string(array, delimiter[, null_string])") .with_sql_example( r#"```sql > select array_to_string([[1, 2, 3, 4], [5, 6, 7, 8]], ','); @@ -290,12 +289,11 @@ static DOCUMENTATION_STRING_TO_ARRAY: OnceLock = OnceLock::new(); fn get_string_to_array_doc() -> &'static Documentation { DOCUMENTATION_STRING_TO_ARRAY.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ARRAY) - .with_description( + Documentation::builder( + DOC_SECTION_ARRAY, "Splits a string into an array of substrings based on a delimiter. Any substrings matching the optional `null_str` argument are replaced with NULL.", - ) - .with_syntax_example("string_to_array(str, delimiter[, null_str])") + + "string_to_array(str, delimiter[, null_str])") .with_sql_example( r#"```sql > select string_to_array('abc##def', '##'); diff --git a/datafusion/functions-window/src/cume_dist.rs b/datafusion/functions-window/src/cume_dist.rs index ae89c1afeec8..2523fd1cfe57 100644 --- a/datafusion/functions-window/src/cume_dist.rs +++ b/datafusion/functions-window/src/cume_dist.rs @@ -94,12 +94,7 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_cume_dist_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_RANKING) - .with_description( - "Relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).", - ) - .with_syntax_example("cume_dist()") + Documentation::builder(DOC_SECTION_RANKING, "Relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).", "cume_dist()") .build() }) } diff --git a/datafusion/functions-window/src/lead_lag.rs b/datafusion/functions-window/src/lead_lag.rs index daaaa3659d5d..d73a5d86bbe6 100644 --- a/datafusion/functions-window/src/lead_lag.rs +++ b/datafusion/functions-window/src/lead_lag.rs @@ -152,14 +152,9 @@ static LAG_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_lag_doc() -> &'static Documentation { LAG_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ANALYTICAL) - .with_description( - "Returns value evaluated at the row that is offset rows before the \ + Documentation::builder(DOC_SECTION_ANALYTICAL, "Returns value evaluated at the row that is offset rows before the \ current row within the partition; if there is no such row, instead return default \ - (which must be of the same type as value).", - ) - .with_syntax_example("lag(expression, offset, default)") + (which must be of the same type as value).", "lag(expression, offset, default)") .with_argument("expression", "Expression to operate on") .with_argument("offset", "Integer. Specifies how many rows back \ the value of expression should be retrieved. Defaults to 1.") @@ -173,14 +168,11 @@ static LEAD_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_lead_doc() -> &'static Documentation { LEAD_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ANALYTICAL) - .with_description( + Documentation::builder(DOC_SECTION_ANALYTICAL, "Returns value evaluated at the row that is offset rows after the \ current row within the partition; if there is no such row, instead return default \ (which must be of the same type as value).", - ) - .with_syntax_example("lead(expression, offset, default)") + "lead(expression, offset, default)") .with_argument("expression", "Expression to operate on") .with_argument("offset", "Integer. Specifies how many rows \ forward the value of expression should be retrieved. Defaults to 1.") diff --git a/datafusion/functions-window/src/nth_value.rs b/datafusion/functions-window/src/nth_value.rs index bfce60aae32f..d15e76718b02 100644 --- a/datafusion/functions-window/src/nth_value.rs +++ b/datafusion/functions-window/src/nth_value.rs @@ -131,15 +131,14 @@ static FIRST_VALUE_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_first_value_doc() -> &'static Documentation { FIRST_VALUE_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ANALYTICAL) - .with_description( - "Returns value evaluated at the row that is the first row of the window \ + Documentation::builder( + DOC_SECTION_ANALYTICAL, + "Returns value evaluated at the row that is the first row of the window \ frame.", - ) - .with_syntax_example("first_value(expression)") - .with_argument("expression", "Expression to operate on") - .build() + "first_value(expression)", + ) + .with_argument("expression", "Expression to operate on") + .build() }) } @@ -147,15 +146,14 @@ static LAST_VALUE_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_last_value_doc() -> &'static Documentation { LAST_VALUE_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ANALYTICAL) - .with_description( - "Returns value evaluated at the row that is the last row of the window \ + Documentation::builder( + DOC_SECTION_ANALYTICAL, + "Returns value evaluated at the row that is the last row of the window \ frame.", - ) - .with_syntax_example("last_value(expression)") - .with_argument("expression", "Expression to operate on") - .build() + "last_value(expression)", + ) + .with_argument("expression", "Expression to operate on") + .build() }) } @@ -163,20 +161,19 @@ static NTH_VALUE_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_nth_value_doc() -> &'static Documentation { NTH_VALUE_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_ANALYTICAL) - .with_description( - "Returns value evaluated at the row that is the nth row of the window \ + Documentation::builder( + DOC_SECTION_ANALYTICAL, + "Returns value evaluated at the row that is the nth row of the window \ frame (counting from 1); null if no such row.", - ) - .with_syntax_example("nth_value(expression, n)") - .with_argument( - "expression", - "The name the column of which nth \ + "nth_value(expression, n)", + ) + .with_argument( + "expression", + "The name the column of which nth \ value to retrieve", - ) - .with_argument("n", "Integer. Specifies the n in nth") - .build() + ) + .with_argument("n", "Integer. Specifies the n in nth") + .build() }) } diff --git a/datafusion/functions-window/src/ntile.rs b/datafusion/functions-window/src/ntile.rs index 5e35810fc6f0..06bf32f9859f 100644 --- a/datafusion/functions-window/src/ntile.rs +++ b/datafusion/functions-window/src/ntile.rs @@ -82,12 +82,7 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_ntile_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_RANKING) - .with_description( - "Integer ranging from 1 to the argument value, dividing the partition as equally as possible", - ) - .with_syntax_example("ntile(expression)") + Documentation::builder(DOC_SECTION_RANKING, "Integer ranging from 1 to the argument value, dividing the partition as equally as possible", "ntile(expression)") .with_argument("expression","An integer describing the number groups the partition should be split into") .build() }) diff --git a/datafusion/functions-window/src/rank.rs b/datafusion/functions-window/src/rank.rs index a93400d65c56..dacee90bfad6 100644 --- a/datafusion/functions-window/src/rank.rs +++ b/datafusion/functions-window/src/rank.rs @@ -106,14 +106,13 @@ static RANK_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_rank_doc() -> &'static Documentation { RANK_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_RANKING) - .with_description( + Documentation::builder( + DOC_SECTION_RANKING, "Returns the rank of the current row within its partition, allowing \ gaps between ranks. This function provides a ranking similar to `row_number`, but \ skips ranks for identical values.", - ) - .with_syntax_example("rank()") + + "rank()") .build() }) } @@ -122,14 +121,9 @@ static DENSE_RANK_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_dense_rank_doc() -> &'static Documentation { DENSE_RANK_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_RANKING) - .with_description( - "Returns the rank of the current row without gaps. This function ranks \ + Documentation::builder(DOC_SECTION_RANKING, "Returns the rank of the current row without gaps. This function ranks \ rows in a dense manner, meaning consecutive ranks are assigned even for identical \ - values.", - ) - .with_syntax_example("dense_rank()") + values.", "dense_rank()") .build() }) } @@ -138,13 +132,8 @@ static PERCENT_RANK_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_percent_rank_doc() -> &'static Documentation { PERCENT_RANK_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_RANKING) - .with_description( - "Returns the percentage rank of the current row within its partition. \ - The value ranges from 0 to 1 and is computed as `(rank - 1) / (total_rows - 1)`.", - ) - .with_syntax_example("percent_rank()") + Documentation::builder(DOC_SECTION_RANKING, "Returns the percentage rank of the current row within its partition. \ + The value ranges from 0 to 1 and is computed as `(rank - 1) / (total_rows - 1)`.", "percent_rank()") .build() }) } diff --git a/datafusion/functions-window/src/row_number.rs b/datafusion/functions-window/src/row_number.rs index 60c356321848..72d4e0232365 100644 --- a/datafusion/functions-window/src/row_number.rs +++ b/datafusion/functions-window/src/row_number.rs @@ -66,13 +66,12 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_row_number_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_RANKING) - .with_description( - "Number of the current row within its partition, counting from 1.", - ) - .with_syntax_example("row_number()") - .build() + Documentation::builder( + DOC_SECTION_RANKING, + "Number of the current row within its partition, counting from 1.", + "row_number()", + ) + .build() }) } diff --git a/datafusion/functions/src/core/arrow_cast.rs b/datafusion/functions/src/core/arrow_cast.rs index b4d0ae41858c..3853737d7b5b 100644 --- a/datafusion/functions/src/core/arrow_cast.rs +++ b/datafusion/functions/src/core/arrow_cast.rs @@ -147,10 +147,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_arrow_cast_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_OTHER) - .with_description("Casts a value to a specific Arrow data type.") - .with_syntax_example("arrow_cast(expression, datatype)") + Documentation::builder( + DOC_SECTION_OTHER, + "Casts a value to a specific Arrow data type.", + "arrow_cast(expression, datatype)") .with_sql_example( r#"```sql > select arrow_cast(-5, 'Int8') as a, diff --git a/datafusion/functions/src/core/arrowtypeof.rs b/datafusion/functions/src/core/arrowtypeof.rs index 5e2bff0dfd3c..54684c6f0bfb 100644 --- a/datafusion/functions/src/core/arrowtypeof.rs +++ b/datafusion/functions/src/core/arrowtypeof.rs @@ -85,12 +85,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_arrowtypeof_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_OTHER) - .with_description( + Documentation::builder( + DOC_SECTION_OTHER, "Returns the name of the underlying [Arrow data type](https://docs.rs/arrow/latest/arrow/datatypes/enum.DataType.html) of the expression.", - ) - .with_syntax_example("arrow_typeof(expression)") + + "arrow_typeof(expression)") .with_sql_example( r#"```sql > select arrow_typeof('foo'), arrow_typeof(1); diff --git a/datafusion/functions/src/core/coalesce.rs b/datafusion/functions/src/core/coalesce.rs index ca6076b0d93a..4f9e83fbf0d9 100644 --- a/datafusion/functions/src/core/coalesce.rs +++ b/datafusion/functions/src/core/coalesce.rs @@ -154,10 +154,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_coalesce_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_CONDITIONAL) - .with_description("Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values.") - .with_syntax_example("coalesce(expression1[, ..., expression_n])") + Documentation::builder( + DOC_SECTION_CONDITIONAL, + "Returns the first of its arguments that is not _null_. Returns _null_ if all arguments are _null_. This function is often used to substitute a default value for _null_ values.", + "coalesce(expression1[, ..., expression_n])") .with_sql_example(r#"```sql > select coalesce(null, null, 'datafusion'); +----------------------------------------+ diff --git a/datafusion/functions/src/core/getfield.rs b/datafusion/functions/src/core/getfield.rs index c6093800b7c8..5c8e1e803e0f 100644 --- a/datafusion/functions/src/core/getfield.rs +++ b/datafusion/functions/src/core/getfield.rs @@ -249,13 +249,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_getfield_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_OTHER) - .with_description(r#"Returns a field within a map or a struct with the given key. + Documentation::builder( + DOC_SECTION_OTHER, + r#"Returns a field within a map or a struct with the given key. Note: most users invoke `get_field` indirectly via field access syntax such as `my_struct_col['field_name']` which results in a call to -`get_field(my_struct_col, 'field_name')`."#) - .with_syntax_example("get_field(expression1, expression2)") +`get_field(my_struct_col, 'field_name')`."#, + "get_field(expression1, expression2)") .with_sql_example(r#"```sql > create table t (idx varchar, v varchar) as values ('data','fusion'), ('apache', 'arrow'); > select struct(idx, v) from t as c; diff --git a/datafusion/functions/src/core/greatest.rs b/datafusion/functions/src/core/greatest.rs index 6fe09cba1faf..3ea2eadf22ee 100644 --- a/datafusion/functions/src/core/greatest.rs +++ b/datafusion/functions/src/core/greatest.rs @@ -231,10 +231,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_greatest_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_CONDITIONAL) - .with_description("Returns the greatest value in a list of expressions. Returns _null_ if all expressions are _null_.") - .with_syntax_example("greatest(expression1[, ..., expression_n])") + Documentation::builder( + DOC_SECTION_CONDITIONAL, + "Returns the greatest value in a list of expressions. Returns _null_ if all expressions are _null_.", + "greatest(expression1[, ..., expression_n])") .with_sql_example(r#"```sql > select greatest(4, 7, 5); +---------------------------+ diff --git a/datafusion/functions/src/core/named_struct.rs b/datafusion/functions/src/core/named_struct.rs index 053f5a81b6cf..556cad1de1ac 100644 --- a/datafusion/functions/src/core/named_struct.rs +++ b/datafusion/functions/src/core/named_struct.rs @@ -175,10 +175,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_named_struct_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRUCT) - .with_description("Returns an Arrow struct using the specified name and input expressions pairs.") - .with_syntax_example("named_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input])") + Documentation::builder( + DOC_SECTION_STRUCT, + "Returns an Arrow struct using the specified name and input expressions pairs.", + "named_struct(expression1_name, expression1_input[, ..., expression_n_name, expression_n_input])") .with_sql_example(r#" For example, this query converts two columns `a` and `b` to a single column with a struct type of fields `field_a` and `field_b`: diff --git a/datafusion/functions/src/core/nullif.rs b/datafusion/functions/src/core/nullif.rs index fceee12a584d..0c2d01376de9 100644 --- a/datafusion/functions/src/core/nullif.rs +++ b/datafusion/functions/src/core/nullif.rs @@ -92,11 +92,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_nullif_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_CONDITIONAL) - .with_description("Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. -This can be used to perform the inverse operation of [`coalesce`](#coalesce).") - .with_syntax_example("nullif(expression1, expression2)") + Documentation::builder( + DOC_SECTION_CONDITIONAL, + "Returns _null_ if _expression1_ equals _expression2_; otherwise it returns _expression1_. +This can be used to perform the inverse operation of [`coalesce`](#coalesce).", + "nullif(expression1, expression2)") .with_sql_example(r#"```sql > select nullif('datafusion', 'data'); +-----------------------------------------+ diff --git a/datafusion/functions/src/core/nvl.rs b/datafusion/functions/src/core/nvl.rs index 18a0d04d0c54..6c470eca3d46 100644 --- a/datafusion/functions/src/core/nvl.rs +++ b/datafusion/functions/src/core/nvl.rs @@ -109,10 +109,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_nvl_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_CONDITIONAL) - .with_description("Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_.") - .with_syntax_example("nvl(expression1, expression2)") + Documentation::builder( + DOC_SECTION_CONDITIONAL, + "Returns _expression2_ if _expression1_ is NULL otherwise it returns _expression1_.", + "nvl(expression1, expression2)") .with_sql_example(r#"```sql > select nvl(null, 'a'); +---------------------+ diff --git a/datafusion/functions/src/core/nvl2.rs b/datafusion/functions/src/core/nvl2.rs index 24f084c985cf..a37292683260 100644 --- a/datafusion/functions/src/core/nvl2.rs +++ b/datafusion/functions/src/core/nvl2.rs @@ -105,10 +105,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_nvl2_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_CONDITIONAL) - .with_description("Returns _expression2_ if _expression1_ is not NULL; otherwise it returns _expression3_.") - .with_syntax_example("nvl2(expression1, expression2, expression3)") + Documentation::builder( + DOC_SECTION_CONDITIONAL, + "Returns _expression2_ if _expression1_ is not NULL; otherwise it returns _expression3_.", + "nvl2(expression1, expression2, expression3)") .with_sql_example(r#"```sql > select nvl2(null, 'a', 'b'); +--------------------------------+ diff --git a/datafusion/functions/src/core/struct.rs b/datafusion/functions/src/core/struct.rs index bc4979e05f02..b7579ba5e4a4 100644 --- a/datafusion/functions/src/core/struct.rs +++ b/datafusion/functions/src/core/struct.rs @@ -118,12 +118,12 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_struct_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRUCT) - .with_description("Returns an Arrow struct using the specified input expressions optionally named. + Documentation::builder( + DOC_SECTION_STRUCT, + "Returns an Arrow struct using the specified input expressions optionally named. Fields in the returned struct use the optional name or the `cN` naming convention. -For example: `c0`, `c1`, `c2`, etc.") - .with_syntax_example("struct(expression1[, ..., expression_n])") +For example: `c0`, `c1`, `c2`, etc.", + "struct(expression1[, ..., expression_n])") .with_sql_example(r#"For example, this query converts two columns `a` and `b` to a single column with a struct type of fields `field_a` and `c1`: ```sql diff --git a/datafusion/functions/src/core/version.rs b/datafusion/functions/src/core/version.rs index 84bf838e9a9c..bfc87f28ebeb 100644 --- a/datafusion/functions/src/core/version.rs +++ b/datafusion/functions/src/core/version.rs @@ -94,12 +94,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_version_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_OTHER) - .with_description("Returns the version of DataFusion.") - .with_syntax_example("version()") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_OTHER, + "Returns the version of DataFusion.", + "version()", + ) + .with_sql_example( + r#"```sql > select version(); +--------------------------------------------+ | version() | @@ -107,8 +108,8 @@ fn get_version_doc() -> &'static Documentation { | Apache DataFusion 42.0.0, aarch64 on macos | +--------------------------------------------+ ```"#, - ) - .build() + ) + .build() }) } diff --git a/datafusion/functions/src/crypto/digest.rs b/datafusion/functions/src/crypto/digest.rs index 6f176f4c96cb..0d2d130cdd71 100644 --- a/datafusion/functions/src/crypto/digest.rs +++ b/datafusion/functions/src/crypto/digest.rs @@ -86,14 +86,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_digest_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_HASHING) - .with_description( - "Computes the binary hash of an expression using the specified algorithm.", - ) - .with_syntax_example("digest(expression, algorithm)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_HASHING, + "Computes the binary hash of an expression using the specified algorithm.", + "digest(expression, algorithm)", + ) + .with_sql_example( + r#"```sql > select digest('foo', 'sha256'); +------------------------------------------+ | digest(Utf8("foo"), Utf8("sha256")) | @@ -101,12 +100,11 @@ fn get_digest_doc() -> &'static Documentation { | | +------------------------------------------+ ```"#, - ) - .with_standard_argument( - "expression", Some("String")) - .with_argument( - "algorithm", - "String expression specifying algorithm to use. Must be one of: + ) + .with_standard_argument("expression", Some("String")) + .with_argument( + "algorithm", + "String expression specifying algorithm to use. Must be one of: - md5 - sha224 @@ -116,7 +114,7 @@ fn get_digest_doc() -> &'static Documentation { - blake2s - blake2b - blake3", - ) - .build() + ) + .build() }) } diff --git a/datafusion/functions/src/crypto/md5.rs b/datafusion/functions/src/crypto/md5.rs index 0d92c6960b25..e6cc59a4a4f7 100644 --- a/datafusion/functions/src/crypto/md5.rs +++ b/datafusion/functions/src/crypto/md5.rs @@ -102,12 +102,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_md5_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_HASHING) - .with_description("Computes an MD5 128-bit checksum for a string expression.") - .with_syntax_example("md5(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_HASHING, + "Computes an MD5 128-bit checksum for a string expression.", + "md5(expression)", + ) + .with_sql_example( + r#"```sql > select md5('foo'); +-------------------------------------+ | md5(Utf8("foo")) | @@ -115,8 +116,8 @@ fn get_md5_doc() -> &'static Documentation { | | +-------------------------------------+ ```"#, - ) - .with_standard_argument("expression", Some("String")) - .build() + ) + .with_standard_argument("expression", Some("String")) + .build() }) } diff --git a/datafusion/functions/src/crypto/sha224.rs b/datafusion/functions/src/crypto/sha224.rs index 91debde38cf0..eba22bb3de37 100644 --- a/datafusion/functions/src/crypto/sha224.rs +++ b/datafusion/functions/src/crypto/sha224.rs @@ -54,12 +54,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_sha224_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_HASHING) - .with_description("Computes the SHA-224 hash of a binary string.") - .with_syntax_example("sha224(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_HASHING, + "Computes the SHA-224 hash of a binary string.", + "sha224(expression)", + ) + .with_sql_example( + r#"```sql > select sha224('foo'); +------------------------------------------+ | sha224(Utf8("foo")) | @@ -67,9 +68,9 @@ fn get_sha224_doc() -> &'static Documentation { | | +------------------------------------------+ ```"#, - ) - .with_standard_argument("expression", Some("String")) - .build() + ) + .with_standard_argument("expression", Some("String")) + .build() }) } diff --git a/datafusion/functions/src/crypto/sha256.rs b/datafusion/functions/src/crypto/sha256.rs index 4fe21a97ac4d..9343fa0af942 100644 --- a/datafusion/functions/src/crypto/sha256.rs +++ b/datafusion/functions/src/crypto/sha256.rs @@ -82,12 +82,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_sha256_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_HASHING) - .with_description("Computes the SHA-256 hash of a binary string.") - .with_syntax_example("sha256(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_HASHING, + "Computes the SHA-256 hash of a binary string.", + "sha256(expression)", + ) + .with_sql_example( + r#"```sql > select sha256('foo'); +--------------------------------------+ | sha256(Utf8("foo")) | @@ -95,8 +96,8 @@ fn get_sha256_doc() -> &'static Documentation { | | +--------------------------------------+ ```"#, - ) - .with_standard_argument("expression", Some("String")) - .build() + ) + .with_standard_argument("expression", Some("String")) + .build() }) } diff --git a/datafusion/functions/src/crypto/sha384.rs b/datafusion/functions/src/crypto/sha384.rs index b6026a304361..495036d02474 100644 --- a/datafusion/functions/src/crypto/sha384.rs +++ b/datafusion/functions/src/crypto/sha384.rs @@ -82,12 +82,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_sha384_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_HASHING) - .with_description("Computes the SHA-384 hash of a binary string.") - .with_syntax_example("sha384(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_HASHING, + "Computes the SHA-384 hash of a binary string.", + "sha384(expression)", + ) + .with_sql_example( + r#"```sql > select sha384('foo'); +-----------------------------------------+ | sha384(Utf8("foo")) | @@ -95,8 +96,8 @@ fn get_sha384_doc() -> &'static Documentation { | | +-----------------------------------------+ ```"#, - ) - .with_standard_argument("expression", Some("String")) - .build() + ) + .with_standard_argument("expression", Some("String")) + .build() }) } diff --git a/datafusion/functions/src/crypto/sha512.rs b/datafusion/functions/src/crypto/sha512.rs index 672b0f52d098..7d454ff8da35 100644 --- a/datafusion/functions/src/crypto/sha512.rs +++ b/datafusion/functions/src/crypto/sha512.rs @@ -82,12 +82,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_sha512_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_HASHING) - .with_description("Computes the SHA-512 hash of a binary string.") - .with_syntax_example("sha512(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_HASHING, + "Computes the SHA-512 hash of a binary string.", + "sha512(expression)", + ) + .with_sql_example( + r#"```sql > select sha512('foo'); +-------------------------------------------+ | sha512(Utf8("foo")) | @@ -95,8 +96,8 @@ fn get_sha512_doc() -> &'static Documentation { | | +-------------------------------------------+ ```"#, - ) - .with_argument("expression", "String") - .build() + ) + .with_argument("expression", "String") + .build() }) } diff --git a/datafusion/functions/src/datetime/current_date.rs b/datafusion/functions/src/datetime/current_date.rs index 28b29adb230b..97d97939d329 100644 --- a/datafusion/functions/src/datetime/current_date.rs +++ b/datafusion/functions/src/datetime/current_date.rs @@ -113,14 +113,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_current_date_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description(r#" + Documentation::builder( + DOC_SECTION_DATETIME, + r#" Returns the current UTC date. The `current_date()` return value is determined at query time and will return the same date, no matter when in the query plan the function executes. -"#) - .with_syntax_example("current_date()") +"#, + "current_date()") .build() }) } diff --git a/datafusion/functions/src/datetime/current_time.rs b/datafusion/functions/src/datetime/current_time.rs index cdb6a10be156..1cd39e5777ea 100644 --- a/datafusion/functions/src/datetime/current_time.rs +++ b/datafusion/functions/src/datetime/current_time.rs @@ -101,14 +101,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_current_time_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description(r#" + Documentation::builder( + DOC_SECTION_DATETIME, + r#" Returns the current UTC time. The `current_time()` return value is determined at query time and will return the same time, no matter when in the query plan the function executes. -"#) - .with_syntax_example("current_time()") +"#, + "current_time()") .build() }) } diff --git a/datafusion/functions/src/datetime/date_bin.rs b/datafusion/functions/src/datetime/date_bin.rs index cb64fb894624..49bf00d5c17b 100644 --- a/datafusion/functions/src/datetime/date_bin.rs +++ b/datafusion/functions/src/datetime/date_bin.rs @@ -177,14 +177,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_date_bin_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description(r#" + Documentation::builder( + DOC_SECTION_DATETIME, + r#" Calculates time intervals and returns the start of the interval nearest to the specified timestamp. Use `date_bin` to downsample time series data by grouping rows into time-based "bins" or "windows" and applying an aggregate or selector function to each window. For example, if you "bin" or "window" data into 15 minute intervals, an input timestamp of `2023-01-01T18:18:18Z` will be updated to the start time of the 15 minute bin it is in: `2023-01-01T18:15:00Z`. -"#) - .with_syntax_example("date_bin(interval, expression, origin-timestamp)") +"#, + "date_bin(interval, expression, origin-timestamp)") .with_sql_example(r#"```sql -- Bin the timestamp into 1 day intervals > SELECT date_bin(interval '1 day', time) as bin diff --git a/datafusion/functions/src/datetime/date_part.rs b/datafusion/functions/src/datetime/date_part.rs index 914ec2df3875..b8c58a11d999 100644 --- a/datafusion/functions/src/datetime/date_part.rs +++ b/datafusion/functions/src/datetime/date_part.rs @@ -253,10 +253,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_date_part_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Returns the specified part of the date as an integer.") - .with_syntax_example("date_part(part, expression)") + Documentation::builder( + DOC_SECTION_DATETIME, + "Returns the specified part of the date as an integer.", + "date_part(part, expression)") .with_argument( "part", r#"Part of the date to return. The following date parts are supported: diff --git a/datafusion/functions/src/datetime/date_trunc.rs b/datafusion/functions/src/datetime/date_trunc.rs index 1559633d7031..b9f3bbf65973 100644 --- a/datafusion/functions/src/datetime/date_trunc.rs +++ b/datafusion/functions/src/datetime/date_trunc.rs @@ -255,13 +255,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_date_trunc_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Truncates a timestamp value to a specified precision.") - .with_syntax_example("date_trunc(precision, expression)") - .with_argument( - "precision", - r#"Time precision to truncate to. The following precisions are supported: + Documentation::builder( + DOC_SECTION_DATETIME, + "Truncates a timestamp value to a specified precision.", + "date_trunc(precision, expression)", + ) + .with_argument( + "precision", + r#"Time precision to truncate to. The following precisions are supported: - year / YEAR - quarter / QUARTER @@ -272,12 +273,12 @@ fn get_date_trunc_doc() -> &'static Documentation { - minute / MINUTE - second / SECOND "#, - ) - .with_argument( - "expression", - "Time expression to operate on. Can be a constant, column, or function.", - ) - .build() + ) + .with_argument( + "expression", + "Time expression to operate on. Can be a constant, column, or function.", + ) + .build() }) } diff --git a/datafusion/functions/src/datetime/from_unixtime.rs b/datafusion/functions/src/datetime/from_unixtime.rs index f654d81a64d0..374c744915f7 100644 --- a/datafusion/functions/src/datetime/from_unixtime.rs +++ b/datafusion/functions/src/datetime/from_unixtime.rs @@ -133,10 +133,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_from_unixtime_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`) return the corresponding timestamp.") - .with_syntax_example("from_unixtime(expression[, timezone])") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts an integer to RFC3339 timestamp format (`YYYY-MM-DDT00:00:00.000000000Z`). Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`) return the corresponding timestamp.", + "from_unixtime(expression[, timezone])") .with_standard_argument("expression", None) .with_argument( "timezone", diff --git a/datafusion/functions/src/datetime/make_date.rs b/datafusion/functions/src/datetime/make_date.rs index c146b2cf9e46..a9340f82f23d 100644 --- a/datafusion/functions/src/datetime/make_date.rs +++ b/datafusion/functions/src/datetime/make_date.rs @@ -164,10 +164,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_make_date_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Make a date from year/month/day component parts.") - .with_syntax_example("make_date(year, month, day)") + Documentation::builder( + DOC_SECTION_DATETIME, + "Make a date from year/month/day component parts.", + "make_date(year, month, day)") .with_argument( "year", " Year to use when making the date. Can be a constant, column or function, and any combination of arithmetic operators.", ) diff --git a/datafusion/functions/src/datetime/now.rs b/datafusion/functions/src/datetime/now.rs index 8129920fe784..58381473a9ab 100644 --- a/datafusion/functions/src/datetime/now.rs +++ b/datafusion/functions/src/datetime/now.rs @@ -110,14 +110,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_to_unixtime_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description(r#" + Documentation::builder( + DOC_SECTION_DATETIME, + r#" Returns the current UTC timestamp. The `now()` return value is determined at query time and will return the same timestamp, no matter when in the query plan the function executes. -"#) - .with_syntax_example("now()") +"#, + "now()") .build() }) } diff --git a/datafusion/functions/src/datetime/to_char.rs b/datafusion/functions/src/datetime/to_char.rs index f16bdfa6c114..4e3fcd1dc13a 100644 --- a/datafusion/functions/src/datetime/to_char.rs +++ b/datafusion/functions/src/datetime/to_char.rs @@ -151,10 +151,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_to_char_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Returns a string representation of a date, time, timestamp or duration based on a [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). Unlike the PostgreSQL equivalent of this function numerical formatting is not supported.") - .with_syntax_example("to_char(expression, format)") + Documentation::builder( + DOC_SECTION_DATETIME, + "Returns a string representation of a date, time, timestamp or duration based on a [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). Unlike the PostgreSQL equivalent of this function numerical formatting is not supported.", + "to_char(expression, format)") .with_argument( "expression", " Expression to operate on. Can be a constant, column, or function that results in a date, time, timestamp or duration." diff --git a/datafusion/functions/src/datetime/to_date.rs b/datafusion/functions/src/datetime/to_date.rs index a3807b3c3c26..15f1159ef984 100644 --- a/datafusion/functions/src/datetime/to_date.rs +++ b/datafusion/functions/src/datetime/to_date.rs @@ -30,7 +30,7 @@ use std::any::Any; use std::sync::OnceLock; #[user_doc( - doc_section(include = "true", label = "Time and Date Functions"), + doc_section(label = "Time and Date Functions"), description = r"Converts a value to a date (`YYYY-MM-DD`). Supports strings, integer and double types as input. Strings are parsed as YYYY-MM-DD (e.g. '2023-07-20') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. diff --git a/datafusion/functions/src/datetime/to_local_time.rs b/datafusion/functions/src/datetime/to_local_time.rs index c369b50f6b7a..eaa91d1140ba 100644 --- a/datafusion/functions/src/datetime/to_local_time.rs +++ b/datafusion/functions/src/datetime/to_local_time.rs @@ -367,10 +367,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_to_local_time_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts a timestamp with a timezone to a timestamp without a timezone (with no offset or timezone information). This function handles daylight saving time changes.") - .with_syntax_example("to_local_time(expression)") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts a timestamp with a timezone to a timestamp without a timezone (with no offset or timezone information). This function handles daylight saving time changes.", + "to_local_time(expression)") .with_argument( "expression", "Time expression to operate on. Can be a constant, column, or function." diff --git a/datafusion/functions/src/datetime/to_timestamp.rs b/datafusion/functions/src/datetime/to_timestamp.rs index 36437b0dee9a..430d4a970810 100644 --- a/datafusion/functions/src/datetime/to_timestamp.rs +++ b/datafusion/functions/src/datetime/to_timestamp.rs @@ -197,14 +197,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_to_timestamp_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description(r#" + Documentation::builder( + DOC_SECTION_DATETIME, + r#" Converts a value to a timestamp (`YYYY-MM-DDT00:00:00Z`). Supports strings, integer, unsigned integer, and double types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats] are provided. Integers, unsigned integers, and doubles are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp. Note: `to_timestamp` returns `Timestamp(Nanosecond)`. The supported range for integer input is between `-9223372037` and `9223372036`. Supported range for string input is between `1677-09-21T00:12:44.0` and `2262-04-11T23:47:16.0`. Please use `to_timestamp_seconds` for the input outside of supported bounds. -"#) - .with_syntax_example("to_timestamp(expression[, ..., format_n])") +"#, + "to_timestamp(expression[, ..., format_n])") .with_argument( "expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators." @@ -292,10 +292,10 @@ static TO_TIMESTAMP_SECONDS_DOC: OnceLock = OnceLock::new(); fn get_to_timestamp_seconds_doc() -> &'static Documentation { TO_TIMESTAMP_SECONDS_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. Integers and unsigned integers are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp.") - .with_syntax_example("to_timestamp_seconds(expression[, ..., format_n])") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. Integers and unsigned integers are interpreted as seconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp.", + "to_timestamp_seconds(expression[, ..., format_n])") .with_argument( "expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators." @@ -385,10 +385,10 @@ static TO_TIMESTAMP_MILLIS_DOC: OnceLock = OnceLock::new(); fn get_to_timestamp_millis_doc() -> &'static Documentation { TO_TIMESTAMP_MILLIS_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided. Integers and unsigned integers are interpreted as milliseconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp.") - .with_syntax_example("to_timestamp_millis(expression[, ..., format_n])") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided. Integers and unsigned integers are interpreted as milliseconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp.", + "to_timestamp_millis(expression[, ..., format_n])") .with_argument( "expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators." @@ -478,10 +478,10 @@ static TO_TIMESTAMP_MICROS_DOC: OnceLock = OnceLock::new(); fn get_to_timestamp_micros_doc() -> &'static Documentation { TO_TIMESTAMP_MICROS_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. Integers and unsigned integers are interpreted as microseconds since the unix epoch (`1970-01-01T00:00:00Z`) Returns the corresponding timestamp.") - .with_syntax_example("to_timestamp_micros(expression[, ..., format_n])") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. Integers and unsigned integers are interpreted as microseconds since the unix epoch (`1970-01-01T00:00:00Z`) Returns the corresponding timestamp.", + "to_timestamp_micros(expression[, ..., format_n])") .with_argument( "expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators." @@ -571,10 +571,10 @@ static TO_TIMESTAMP_NANOS_DOC: OnceLock = OnceLock::new(); fn get_to_timestamp_nanos_doc() -> &'static Documentation { TO_TIMESTAMP_NANOS_DOC.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp.") - .with_syntax_example("to_timestamp_nanos(expression[, ..., format_n])") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts a value to a timestamp (`YYYY-MM-DDT00:00:00.000000000Z`). Supports strings, integer, and unsigned integer types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html)s are provided. Integers and unsigned integers are interpreted as nanoseconds since the unix epoch (`1970-01-01T00:00:00Z`). Returns the corresponding timestamp.", + "to_timestamp_nanos(expression[, ..., format_n])") .with_argument( "expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators." diff --git a/datafusion/functions/src/datetime/to_unixtime.rs b/datafusion/functions/src/datetime/to_unixtime.rs index 74ee954a50ac..9e6453a597c3 100644 --- a/datafusion/functions/src/datetime/to_unixtime.rs +++ b/datafusion/functions/src/datetime/to_unixtime.rs @@ -101,10 +101,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_to_unixtime_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_DATETIME) - .with_description("Converts a value to seconds since the unix epoch (`1970-01-01T00:00:00Z`). Supports strings, dates, timestamps and double types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided.") - .with_syntax_example("to_unixtime(expression[, ..., format_n])") + Documentation::builder( + DOC_SECTION_DATETIME, + "Converts a value to seconds since the unix epoch (`1970-01-01T00:00:00Z`). Supports strings, dates, timestamps and double types as input. Strings are parsed as RFC3339 (e.g. '2023-07-20T05:44:00') if no [Chrono formats](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) are provided.", + "to_unixtime(expression[, ..., format_n])") .with_argument( "expression", "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators." diff --git a/datafusion/functions/src/encoding/inner.rs b/datafusion/functions/src/encoding/inner.rs index ad2eb1e3bb6f..42d2ff98c39d 100644 --- a/datafusion/functions/src/encoding/inner.rs +++ b/datafusion/functions/src/encoding/inner.rs @@ -62,14 +62,15 @@ static ENCODE_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_encode_doc() -> &'static Documentation { ENCODE_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_BINARY_STRING) - .with_description("Encode binary data into a textual representation.") - .with_syntax_example("encode(expression, format)") - .with_argument("expression", "Expression containing string or binary data") - .with_argument("format", "Supported formats are: `base64`, `hex`") - .with_related_udf("decode") - .build() + Documentation::builder( + DOC_SECTION_BINARY_STRING, + "Encode binary data into a textual representation.", + "encode(expression, format)", + ) + .with_argument("expression", "Expression containing string or binary data") + .with_argument("format", "Supported formats are: `base64`, `hex`") + .with_related_udf("decode") + .build() }) } @@ -152,14 +153,15 @@ static DECODE_DOCUMENTATION: OnceLock = OnceLock::new(); fn get_decode_doc() -> &'static Documentation { DECODE_DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_BINARY_STRING) - .with_description("Decode binary data from textual representation in string.") - .with_syntax_example("decode(expression, format)") - .with_argument("expression", "Expression containing encoded string data") - .with_argument("format", "Same arguments as [encode](#encode)") - .with_related_udf("encode") - .build() + Documentation::builder( + DOC_SECTION_BINARY_STRING, + "Decode binary data from textual representation in string.", + "decode(expression, format)", + ) + .with_argument("expression", "Expression containing encoded string data") + .with_argument("format", "Same arguments as [encode](#encode)") + .with_related_udf("encode") + .build() }) } diff --git a/datafusion/functions/src/math/abs.rs b/datafusion/functions/src/math/abs.rs index 27f11ac93241..3565afbe6b48 100644 --- a/datafusion/functions/src/math/abs.rs +++ b/datafusion/functions/src/math/abs.rs @@ -201,11 +201,12 @@ static DOCUMENTATION: OnceLock = 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", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the absolute value of a number.", + "abs(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } diff --git a/datafusion/functions/src/math/cot.rs b/datafusion/functions/src/math/cot.rs index 0730caae49b5..2355696a8be7 100644 --- a/datafusion/functions/src/math/cot.rs +++ b/datafusion/functions/src/math/cot.rs @@ -43,12 +43,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_cot_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the cotangent of a number.") - .with_syntax_example(r#"cot(numeric_expression)"#) - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the cotangent of a number.", + r#"cot(numeric_expression)"#, + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } diff --git a/datafusion/functions/src/math/factorial.rs b/datafusion/functions/src/math/factorial.rs index 430f0c58462d..083936eb185a 100644 --- a/datafusion/functions/src/math/factorial.rs +++ b/datafusion/functions/src/math/factorial.rs @@ -85,12 +85,13 @@ static DOCUMENTATION: OnceLock = 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", Some("Numeric")) - .build() + 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() }) } diff --git a/datafusion/functions/src/math/gcd.rs b/datafusion/functions/src/math/gcd.rs index 1e70955874d2..f4119cd975ab 100644 --- a/datafusion/functions/src/math/gcd.rs +++ b/datafusion/functions/src/math/gcd.rs @@ -85,12 +85,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_gcd_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, "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)") + + "gcd(expression_x, expression_y)") .with_standard_argument("expression_x", Some("First numeric")) .with_standard_argument("expression_y", Some("Second numeric")) .build() diff --git a/datafusion/functions/src/math/iszero.rs b/datafusion/functions/src/math/iszero.rs index 04aab2b2ec94..c1498ae36222 100644 --- a/datafusion/functions/src/math/iszero.rs +++ b/datafusion/functions/src/math/iszero.rs @@ -88,14 +88,13 @@ static DOCUMENTATION: OnceLock = 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", Some("Numeric")) - .build() + 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() }) } diff --git a/datafusion/functions/src/math/lcm.rs b/datafusion/functions/src/math/lcm.rs index 1a8a7e5fe0db..4e5a9b64f6f5 100644 --- a/datafusion/functions/src/math/lcm.rs +++ b/datafusion/functions/src/math/lcm.rs @@ -86,12 +86,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_lcm_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, "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)") + + "lcm(expression_x, expression_y)") .with_standard_argument("expression_x", Some("First numeric")) .with_standard_argument("expression_y", Some("Second numeric")) .build() diff --git a/datafusion/functions/src/math/log.rs b/datafusion/functions/src/math/log.rs index b0895c390f6b..d4bb8ec13b0b 100644 --- a/datafusion/functions/src/math/log.rs +++ b/datafusion/functions/src/math/log.rs @@ -51,10 +51,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_log_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_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.") - .with_syntax_example(r#"log(base, numeric_expression) + 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")) diff --git a/datafusion/functions/src/math/monotonicity.rs b/datafusion/functions/src/math/monotonicity.rs index 6156cffd8382..46c670b8e651 100644 --- a/datafusion/functions/src/math/monotonicity.rs +++ b/datafusion/functions/src/math/monotonicity.rs @@ -42,12 +42,13 @@ static DOCUMENTATION_ACOS: OnceLock = OnceLock::new(); pub fn get_acos_doc() -> &'static Documentation { DOCUMENTATION_ACOS.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the arc cosine or inverse cosine of a number.") - .with_syntax_example("acos(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the arc cosine or inverse cosine of a number.", + "acos(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -72,12 +73,11 @@ static DOCUMENTATION_ACOSH: OnceLock = OnceLock::new(); pub fn get_acosh_doc() -> &'static Documentation { DOCUMENTATION_ACOSH.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, "Returns the area hyperbolic cosine or inverse hyperbolic cosine of a number.", - ) - .with_syntax_example("acosh(numeric_expression)") + + "acosh(numeric_expression)") .with_standard_argument("numeric_expression", Some("Numeric")) .build() }) @@ -102,12 +102,13 @@ static DOCUMENTATION_ASIN: OnceLock = OnceLock::new(); pub fn get_asin_doc() -> &'static Documentation { DOCUMENTATION_ASIN.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the arc sine or inverse sine of a number.") - .with_syntax_example("asin(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the arc sine or inverse sine of a number.", + "asin(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -120,14 +121,13 @@ static DOCUMENTATION_ASINH: OnceLock = OnceLock::new(); pub fn get_asinh_doc() -> &'static Documentation { DOCUMENTATION_ASINH.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - "Returns the area hyperbolic sine or inverse hyperbolic sine of a number.", - ) - .with_syntax_example("asinh(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the area hyperbolic sine or inverse hyperbolic sine of a number.", + "asinh(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -140,12 +140,13 @@ static DOCUMENTATION_ATAN: OnceLock = OnceLock::new(); pub fn get_atan_doc() -> &'static Documentation { DOCUMENTATION_ATAN.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the arc tangent or inverse tangent of a number.") - .with_syntax_example("atan(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the arc tangent or inverse tangent of a number.", + "atan(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -168,12 +169,11 @@ static DOCUMENTATION_ATANH: OnceLock = OnceLock::new(); pub fn get_atanh_doc() -> &'static Documentation { DOCUMENTATION_ATANH.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, "Returns the area hyperbolic tangent or inverse hyperbolic tangent of a number.", - ) - .with_syntax_example("atanh(numeric_expression)") + + "atanh(numeric_expression)") .with_standard_argument("numeric_expression", Some("Numeric")) .build() }) @@ -189,12 +189,11 @@ static DOCUMENTATION_ATANH2: OnceLock = OnceLock::new(); pub fn get_atan2_doc() -> &'static Documentation { DOCUMENTATION_ATANH2.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, "Returns the arc tangent or inverse tangent of `expression_y / expression_x`.", - ) - .with_syntax_example("atan2(expression_y, expression_x)") + + "atan2(expression_y, expression_x)") .with_argument("expression_y", r#"First numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators."#) .with_argument("expression_x", r#"Second numeric expression to operate on. @@ -212,12 +211,13 @@ static DOCUMENTATION_CBRT: OnceLock = OnceLock::new(); pub fn get_cbrt_doc() -> &'static Documentation { DOCUMENTATION_CBRT.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the cube root of a number.") - .with_syntax_example("cbrt(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the cube root of a number.", + "cbrt(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -230,14 +230,13 @@ static DOCUMENTATION_CEIL: OnceLock = OnceLock::new(); pub fn get_ceil_doc() -> &'static Documentation { DOCUMENTATION_CEIL.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - "Returns the nearest integer greater than or equal to a number.", - ) - .with_syntax_example("ceil(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the nearest integer greater than or equal to a number.", + "ceil(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -252,12 +251,13 @@ static DOCUMENTATION_COS: OnceLock = OnceLock::new(); pub fn get_cos_doc() -> &'static Documentation { DOCUMENTATION_COS.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the cosine of a number.") - .with_syntax_example("cos(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the cosine of a number.", + "cos(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -281,12 +281,13 @@ static DOCUMENTATION_COSH: OnceLock = OnceLock::new(); pub fn get_cosh_doc() -> &'static Documentation { DOCUMENTATION_COSH.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the hyperbolic cosine of a number.") - .with_syntax_example("cosh(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the hyperbolic cosine of a number.", + "cosh(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -299,12 +300,13 @@ static DOCUMENTATION_DEGREES: OnceLock = OnceLock::new(); pub fn get_degrees_doc() -> &'static Documentation { DOCUMENTATION_DEGREES.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Converts radians to degrees.") - .with_syntax_example("degrees(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Converts radians to degrees.", + "degrees(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -317,12 +319,13 @@ static DOCUMENTATION_EXP: OnceLock = OnceLock::new(); pub fn get_exp_doc() -> &'static Documentation { DOCUMENTATION_EXP.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the base-e exponential of a number.") - .with_syntax_example("exp(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the base-e exponential of a number.", + "exp(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -335,14 +338,13 @@ static DOCUMENTATION_FLOOR: OnceLock = OnceLock::new(); pub fn get_floor_doc() -> &'static Documentation { DOCUMENTATION_FLOOR.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - "Returns the nearest integer less than or equal to a number.", - ) - .with_syntax_example("floor(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the nearest integer less than or equal to a number.", + "floor(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -364,12 +366,13 @@ static DOCUMENTATION_LN: OnceLock = OnceLock::new(); pub fn get_ln_doc() -> &'static Documentation { DOCUMENTATION_LN.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the natural logarithm of a number.") - .with_syntax_example("ln(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the natural logarithm of a number.", + "ln(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -391,12 +394,13 @@ static DOCUMENTATION_LOG2: OnceLock = OnceLock::new(); pub fn get_log2_doc() -> &'static Documentation { DOCUMENTATION_LOG2.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the base-2 logarithm of a number.") - .with_syntax_example("log2(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the base-2 logarithm of a number.", + "log2(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -418,12 +422,13 @@ static DOCUMENTATION_LOG10: OnceLock = OnceLock::new(); pub fn get_log10_doc() -> &'static Documentation { DOCUMENTATION_LOG10.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the base-10 logarithm of a number.") - .with_syntax_example("log10(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the base-10 logarithm of a number.", + "log10(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -436,12 +441,13 @@ static DOCUMENTATION_RADIONS: OnceLock = OnceLock::new(); pub fn get_radians_doc() -> &'static Documentation { DOCUMENTATION_RADIONS.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Converts degrees to radians.") - .with_syntax_example("radians(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Converts degrees to radians.", + "radians(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -456,12 +462,13 @@ static DOCUMENTATION_SIN: OnceLock = OnceLock::new(); pub fn get_sin_doc() -> &'static Documentation { DOCUMENTATION_SIN.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the sine of a number.") - .with_syntax_example("sin(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the sine of a number.", + "sin(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -474,12 +481,13 @@ static DOCUMENTATION_SINH: OnceLock = OnceLock::new(); pub fn get_sinh_doc() -> &'static Documentation { DOCUMENTATION_SINH.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the hyperbolic sine of a number.") - .with_syntax_example("sinh(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the hyperbolic sine of a number.", + "sinh(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -501,12 +509,13 @@ static DOCUMENTATION_SQRT: OnceLock = OnceLock::new(); pub fn get_sqrt_doc() -> &'static Documentation { DOCUMENTATION_SQRT.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the square root of a number.") - .with_syntax_example("sqrt(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the square root of a number.", + "sqrt(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -521,12 +530,13 @@ static DOCUMENTATION_TAN: OnceLock = OnceLock::new(); pub fn get_tan_doc() -> &'static Documentation { DOCUMENTATION_TAN.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the tangent of a number.") - .with_syntax_example("tan(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the tangent of a number.", + "tan(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } @@ -539,11 +549,12 @@ static DOCUMENTATION_TANH: OnceLock = OnceLock::new(); pub fn get_tanh_doc() -> &'static Documentation { DOCUMENTATION_TANH.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns the hyperbolic tangent of a number.") - .with_syntax_example("tanh(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + Documentation::builder( + DOC_SECTION_MATH, + "Returns the hyperbolic tangent of a number.", + "tanh(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } diff --git a/datafusion/functions/src/math/nans.rs b/datafusion/functions/src/math/nans.rs index 2898fee593c9..4cfbf0494812 100644 --- a/datafusion/functions/src/math/nans.rs +++ b/datafusion/functions/src/math/nans.rs @@ -105,13 +105,12 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_isnan_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - "Returns true if a given number is +NaN or -NaN otherwise returns false.", - ) - .with_syntax_example("isnan(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + 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() }) } diff --git a/datafusion/functions/src/math/nanvl.rs b/datafusion/functions/src/math/nanvl.rs index d8dd6817f952..0715dc7f7eac 100644 --- a/datafusion/functions/src/math/nanvl.rs +++ b/datafusion/functions/src/math/nanvl.rs @@ -90,13 +90,12 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_nanvl_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, r#"Returns the first argument if it's not _NaN_. Returns the second argument otherwise."#, - ) - .with_syntax_example("nanvl(expression_x, expression_y)") + + "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() diff --git a/datafusion/functions/src/math/pi.rs b/datafusion/functions/src/math/pi.rs index 7b494cc55df4..a96ca176622d 100644 --- a/datafusion/functions/src/math/pi.rs +++ b/datafusion/functions/src/math/pi.rs @@ -90,10 +90,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_pi_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Returns an approximate value of π.") - .with_syntax_example("pi()") - .build() + 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 5bef0eac8f96..92dd8966b66c 100644 --- a/datafusion/functions/src/math/power.rs +++ b/datafusion/functions/src/math/power.rs @@ -178,15 +178,14 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_power_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - "Returns a base expression raised to the power of an exponent.", - ) - .with_syntax_example("power(base, exponent)") - .with_standard_argument("base", Some("Numeric")) - .with_standard_argument("exponent", Some("Exponent numeric")) - .build() + 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() }) } diff --git a/datafusion/functions/src/math/random.rs b/datafusion/functions/src/math/random.rs index 0d9888fa4a02..e34db023ed9a 100644 --- a/datafusion/functions/src/math/random.rs +++ b/datafusion/functions/src/math/random.rs @@ -90,13 +90,12 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_random_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - r#"Returns a random float value in the range [0, 1). + Documentation::builder( + DOC_SECTION_MATH, + r#"Returns a random float value in the range [0, 1). The random seed is unique to each row."#, - ) - .with_syntax_example("random()") - .build() + "random()", + ) + .build() }) } diff --git a/datafusion/functions/src/math/round.rs b/datafusion/functions/src/math/round.rs index b6898029c6df..cfbf083fcb1e 100644 --- a/datafusion/functions/src/math/round.rs +++ b/datafusion/functions/src/math/round.rs @@ -112,16 +112,17 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_round_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description("Rounds a number to the nearest integer.") - .with_syntax_example("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() + 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() }) } diff --git a/datafusion/functions/src/math/signum.rs b/datafusion/functions/src/math/signum.rs index e567ab71dbc2..eda9df49fbac 100644 --- a/datafusion/functions/src/math/signum.rs +++ b/datafusion/functions/src/math/signum.rs @@ -97,16 +97,15 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_signum_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( - r#"Returns the sign of a number. + Documentation::builder( + DOC_SECTION_MATH, + r#"Returns the sign of a number. Negative numbers return `-1`. Zero and positive numbers return `1`."#, - ) - .with_syntax_example("signum(numeric_expression)") - .with_standard_argument("numeric_expression", Some("Numeric")) - .build() + "signum(numeric_expression)", + ) + .with_standard_argument("numeric_expression", Some("Numeric")) + .build() }) } diff --git a/datafusion/functions/src/math/trunc.rs b/datafusion/functions/src/math/trunc.rs index d0e0fb7b251e..c2787c4577d0 100644 --- a/datafusion/functions/src/math/trunc.rs +++ b/datafusion/functions/src/math/trunc.rs @@ -117,12 +117,11 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_trunc_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_MATH) - .with_description( + Documentation::builder( + DOC_SECTION_MATH, "Truncates a number to a whole number or truncated to the specified decimal places.", - ) - .with_syntax_example("trunc(numeric_expression[, 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 diff --git a/datafusion/functions/src/regex/regexpcount.rs b/datafusion/functions/src/regex/regexpcount.rs index 13eefe2ff3e4..a667d70e7bb2 100644 --- a/datafusion/functions/src/regex/regexpcount.rs +++ b/datafusion/functions/src/regex/regexpcount.rs @@ -119,10 +119,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_regexp_count_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_REGEX) - .with_description("Returns the number of matches that a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has in a string.") - .with_syntax_example("regexp_count(str, regexp[, start, flags])") + Documentation::builder( + DOC_SECTION_REGEX, + "Returns the number of matches that a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has in a string.", + "regexp_count(str, regexp[, start, flags])") .with_sql_example(r#"```sql > select regexp_count('abcAbAbc', 'abc', 2, 'i'); +---------------------------------------------------------------+ diff --git a/datafusion/functions/src/regex/regexplike.rs b/datafusion/functions/src/regex/regexplike.rs index f4b62b9f201f..adbd6ef94d84 100644 --- a/datafusion/functions/src/regex/regexplike.rs +++ b/datafusion/functions/src/regex/regexplike.rs @@ -47,10 +47,7 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_regexp_like_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_REGEX) - .with_description("Returns true if a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has at least one match in a string, false otherwise.") - .with_syntax_example("regexp_like(str, regexp[, flags])") + Documentation::builder(DOC_SECTION_REGEX,"Returns true if a [regular expression](https://docs.rs/regex/latest/regex/#syntax) has at least one match in a string, false otherwise.","regexp_like(str, regexp[, flags])") .with_sql_example(r#"```sql select regexp_like('Köln', '[a-zA-Z]ö[a-zA-Z]{2}'); +--------------------------------------------------------+ diff --git a/datafusion/functions/src/regex/regexpmatch.rs b/datafusion/functions/src/regex/regexpmatch.rs index 47fead6a7d9a..df4f294bb950 100644 --- a/datafusion/functions/src/regex/regexpmatch.rs +++ b/datafusion/functions/src/regex/regexpmatch.rs @@ -121,10 +121,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_regexp_match_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_REGEX) - .with_description("Returns the first [regular expression](https://docs.rs/regex/latest/regex/#syntax) matches in a string.") - .with_syntax_example("regexp_match(str, regexp[, flags])") + Documentation::builder( + DOC_SECTION_REGEX, + "Returns the first [regular expression](https://docs.rs/regex/latest/regex/#syntax) matches in a string.", + "regexp_match(str, regexp[, flags])") .with_sql_example(r#"```sql > select regexp_match('Köln', '[a-zA-Z]ö[a-zA-Z]{2}'); +---------------------------------------------------------+ diff --git a/datafusion/functions/src/regex/regexpreplace.rs b/datafusion/functions/src/regex/regexpreplace.rs index 8dc25b7e1932..3f289e7c1511 100644 --- a/datafusion/functions/src/regex/regexpreplace.rs +++ b/datafusion/functions/src/regex/regexpreplace.rs @@ -138,10 +138,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_regexp_replace_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_REGEX) - .with_description("Replaces substrings in a string that match a [regular expression](https://docs.rs/regex/latest/regex/#syntax).") - .with_syntax_example("regexp_replace(str, regexp, replacement[, flags])") + Documentation::builder( + DOC_SECTION_REGEX, + "Replaces substrings in a string that match a [regular expression](https://docs.rs/regex/latest/regex/#syntax).", + "regexp_replace(str, regexp, replacement[, flags])") .with_sql_example(r#"```sql > select regexp_replace('foobarbaz', 'b(..)', 'X\\1Y', 'g'); +------------------------------------------------------------------------+ diff --git a/datafusion/functions/src/string/ascii.rs b/datafusion/functions/src/string/ascii.rs index cc1196c70624..4f615b5b2c58 100644 --- a/datafusion/functions/src/string/ascii.rs +++ b/datafusion/functions/src/string/ascii.rs @@ -81,14 +81,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_ascii_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description( - "Returns the Unicode character code of the first character in a string.", - ) - .with_syntax_example("ascii(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns the Unicode character code of the first character in a string.", + "ascii(str)", + ) + .with_sql_example( + r#"```sql > select ascii('abc'); +--------------------+ | ascii(Utf8("abc")) | @@ -102,10 +101,10 @@ fn get_ascii_doc() -> &'static Documentation { | 128640 | +-------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_related_udf("chr") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_related_udf("chr") + .build() }) } diff --git a/datafusion/functions/src/string/bit_length.rs b/datafusion/functions/src/string/bit_length.rs index 3392425046cb..5a23692d85c7 100644 --- a/datafusion/functions/src/string/bit_length.rs +++ b/datafusion/functions/src/string/bit_length.rs @@ -100,12 +100,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_bit_length_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns the bit length of a string.") - .with_syntax_example("bit_length(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns the bit length of a string.", + "bit_length(str)", + ) + .with_sql_example( + r#"```sql > select bit_length('datafusion'); +--------------------------------+ | bit_length(Utf8("datafusion")) | @@ -113,10 +114,10 @@ fn get_bit_length_doc() -> &'static Documentation { | 80 | +--------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_related_udf("length") - .with_related_udf("octet_length") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_related_udf("length") + .with_related_udf("octet_length") + .build() }) } diff --git a/datafusion/functions/src/string/btrim.rs b/datafusion/functions/src/string/btrim.rs index a9bc0ca9f4ae..ae79bb59f9c7 100644 --- a/datafusion/functions/src/string/btrim.rs +++ b/datafusion/functions/src/string/btrim.rs @@ -114,10 +114,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_btrim_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Trims the specified trim string from the start and end of a string. If no trim string is provided, all whitespace is removed from the start and end of the input string.") - .with_syntax_example("btrim(str[, trim_str])") + Documentation::builder( + DOC_SECTION_STRING, + "Trims the specified trim string from the start and end of a string. If no trim string is provided, all whitespace is removed from the start and end of the input string.", + "btrim(str[, trim_str])") .with_sql_example(r#"```sql > select btrim('__datafusion____', '_'); +-------------------------------------------+ diff --git a/datafusion/functions/src/string/chr.rs b/datafusion/functions/src/string/chr.rs index 2efdbffd45a0..127b02cdf733 100644 --- a/datafusion/functions/src/string/chr.rs +++ b/datafusion/functions/src/string/chr.rs @@ -113,14 +113,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_chr_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description( - "Returns the character with the specified ASCII or Unicode code value.", - ) - .with_syntax_example("chr(expression)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns the character with the specified ASCII or Unicode code value.", + "chr(expression)", + ) + .with_sql_example( + r#"```sql > select chr(128640); +--------------------+ | chr(Int64(128640)) | @@ -128,9 +127,9 @@ fn get_chr_doc() -> &'static Documentation { | 🚀 | +--------------------+ ```"#, - ) - .with_standard_argument("expression", Some("String")) - .with_related_udf("ascii") - .build() + ) + .with_standard_argument("expression", Some("String")) + .with_related_udf("ascii") + .build() }) } diff --git a/datafusion/functions/src/string/concat.rs b/datafusion/functions/src/string/concat.rs index a8662a65d047..576c891ce467 100644 --- a/datafusion/functions/src/string/concat.rs +++ b/datafusion/functions/src/string/concat.rs @@ -271,12 +271,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_concat_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Concatenates multiple strings together.") - .with_syntax_example("concat(str[, ..., str_n])") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Concatenates multiple strings together.", + "concat(str[, ..., str_n])", + ) + .with_sql_example( + r#"```sql > select concat('data', 'f', 'us', 'ion'); +-------------------------------------------------------+ | concat(Utf8("data"),Utf8("f"),Utf8("us"),Utf8("ion")) | @@ -284,11 +285,11 @@ fn get_concat_doc() -> &'static Documentation { | datafusion | +-------------------------------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_argument("str_n", "Subsequent string expressions to concatenate.") - .with_related_udf("concat_ws") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_argument("str_n", "Subsequent string expressions to concatenate.") + .with_related_udf("concat_ws") + .build() }) } diff --git a/datafusion/functions/src/string/concat_ws.rs b/datafusion/functions/src/string/concat_ws.rs index 5e9f0d40a665..610c4f0be697 100644 --- a/datafusion/functions/src/string/concat_ws.rs +++ b/datafusion/functions/src/string/concat_ws.rs @@ -279,14 +279,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_concat_ws_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description( - "Concatenates multiple strings together with a specified separator.", - ) - .with_syntax_example("concat_ws(separator, str[, ..., str_n])") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Concatenates multiple strings together with a specified separator.", + "concat_ws(separator, str[, ..., str_n])", + ) + .with_sql_example( + r#"```sql > select concat_ws('_', 'data', 'fusion'); +--------------------------------------------------+ | concat_ws(Utf8("_"),Utf8("data"),Utf8("fusion")) | @@ -294,15 +293,15 @@ fn get_concat_ws_doc() -> &'static Documentation { | data_fusion | +--------------------------------------------------+ ```"#, - ) - .with_argument( - "separator", - "Separator to insert between concatenated strings.", - ) - .with_standard_argument("str", Some("String")) - .with_argument("str_n", "Subsequent string expressions to concatenate.") - .with_related_udf("concat") - .build() + ) + .with_argument( + "separator", + "Separator to insert between concatenated strings.", + ) + .with_standard_argument("str", Some("String")) + .with_argument("str_n", "Subsequent string expressions to concatenate.") + .with_related_udf("concat") + .build() }) } diff --git a/datafusion/functions/src/string/contains.rs b/datafusion/functions/src/string/contains.rs index 420dd27c1f5e..3e5c72ac20e9 100644 --- a/datafusion/functions/src/string/contains.rs +++ b/datafusion/functions/src/string/contains.rs @@ -83,14 +83,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_contains_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description( - "Return true if search_str is found within string (case-sensitive).", - ) - .with_syntax_example("contains(str, search_str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Return true if search_str is found within string (case-sensitive).", + "contains(str, search_str)", + ) + .with_sql_example( + r#"```sql > select contains('the quick brown fox', 'row'); +---------------------------------------------------+ | contains(Utf8("the quick brown fox"),Utf8("row")) | @@ -98,10 +97,10 @@ fn get_contains_doc() -> &'static Documentation { | true | +---------------------------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_argument("search_str", "The string to search for in str.") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_argument("search_str", "The string to search for in str.") + .build() }) } diff --git a/datafusion/functions/src/string/ends_with.rs b/datafusion/functions/src/string/ends_with.rs index f062fec8b8b7..fc7fc04f4363 100644 --- a/datafusion/functions/src/string/ends_with.rs +++ b/datafusion/functions/src/string/ends_with.rs @@ -87,12 +87,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_ends_with_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Tests if a string ends with a substring.") - .with_syntax_example("ends_with(str, substr)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Tests if a string ends with a substring.", + "ends_with(str, substr)", + ) + .with_sql_example( + r#"```sql > select ends_with('datafusion', 'soin'); +--------------------------------------------+ | ends_with(Utf8("datafusion"),Utf8("soin")) | @@ -106,10 +107,10 @@ fn get_ends_with_doc() -> &'static Documentation { | true | +--------------------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_argument("substr", "Substring to test for.") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_argument("substr", "Substring to test for.") + .build() }) } diff --git a/datafusion/functions/src/string/initcap.rs b/datafusion/functions/src/string/initcap.rs index 74876a42a598..a9090b0a6f43 100644 --- a/datafusion/functions/src/string/initcap.rs +++ b/datafusion/functions/src/string/initcap.rs @@ -88,10 +88,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_initcap_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters.") - .with_syntax_example("initcap(str)") + Documentation::builder( + DOC_SECTION_STRING, + "Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters.", + "initcap(str)") .with_sql_example(r#"```sql > select initcap('apache datafusion'); +------------------------------------+ diff --git a/datafusion/functions/src/string/levenshtein.rs b/datafusion/functions/src/string/levenshtein.rs index 62b13f280026..51ff428055e4 100644 --- a/datafusion/functions/src/string/levenshtein.rs +++ b/datafusion/functions/src/string/levenshtein.rs @@ -90,10 +90,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_levenshtein_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns the [`Levenshtein distance`](https://en.wikipedia.org/wiki/Levenshtein_distance) between the two given strings.") - .with_syntax_example("levenshtein(str1, str2)") + Documentation::builder( + DOC_SECTION_STRING, + "Returns the [`Levenshtein distance`](https://en.wikipedia.org/wiki/Levenshtein_distance) between the two given strings.", + "levenshtein(str1, str2)") .with_sql_example(r#"```sql > select levenshtein('kitten', 'sitting'); +---------------------------------------------+ diff --git a/datafusion/functions/src/string/lower.rs b/datafusion/functions/src/string/lower.rs index a4853a55ac19..67c80cb785b6 100644 --- a/datafusion/functions/src/string/lower.rs +++ b/datafusion/functions/src/string/lower.rs @@ -79,12 +79,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_lower_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Converts a string to lower-case.") - .with_syntax_example("lower(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Converts a string to lower-case.", + "lower(str)", + ) + .with_sql_example( + r#"```sql > select lower('Ångström'); +-------------------------+ | lower(Utf8("Ångström")) | @@ -92,11 +93,11 @@ fn get_lower_doc() -> &'static Documentation { | ångström | +-------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_related_udf("initcap") - .with_related_udf("upper") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_related_udf("initcap") + .with_related_udf("upper") + .build() }) } #[cfg(test)] diff --git a/datafusion/functions/src/string/ltrim.rs b/datafusion/functions/src/string/ltrim.rs index ad8a60185c32..93470368803a 100644 --- a/datafusion/functions/src/string/ltrim.rs +++ b/datafusion/functions/src/string/ltrim.rs @@ -18,15 +18,15 @@ use arrow::array::{ArrayRef, OffsetSizeTrait}; use arrow::datatypes::DataType; use std::any::Any; -use std::sync::OnceLock; use crate::string::common::*; use crate::utils::{make_scalar_function, utf8_to_str_type}; use datafusion_common::{exec_err, Result}; use datafusion_expr::function::Hint; -use datafusion_expr::scalar_doc_sections::DOC_SECTION_STRING; use datafusion_expr::{ColumnarValue, Documentation, TypeSignature, Volatility}; use datafusion_expr::{ScalarUDFImpl, Signature}; +use datafusion_macros::user_doc; +use std::sync::OnceLock; /// Returns the longest string with leading characters removed. If the characters are not specified, whitespace is removed. /// ltrim('zzzytest', 'xyz') = 'test' @@ -35,6 +35,33 @@ fn ltrim(args: &[ArrayRef]) -> Result { general_trim::(args, TrimType::Left, use_string_view) } +#[user_doc( + doc_section(label = "String Functions"), + description = "Trims the specified trim string from the beginning of a string. If no trim string is provided, all whitespace is removed from the start of the input string.", + syntax_example = "ltrim(str[, trim_str])", + sql_example = r#"```sql +> select ltrim(' datafusion '); ++-------------------------------+ +| ltrim(Utf8(" datafusion ")) | ++-------------------------------+ +| datafusion | ++-------------------------------+ +> select ltrim('___datafusion___', '_'); ++-------------------------------------------+ +| ltrim(Utf8("___datafusion___"),Utf8("_")) | ++-------------------------------------------+ +| datafusion___ | ++-------------------------------------------+ +```"#, + standard_argument(name = "str", prefix = "String"), + argument( + name = "trim_str", + description = r"String expression to trim from the beginning of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._" + ), + alternative_syntax = "trim(LEADING trim_str FROM str)", + related_udf(name = "btrim"), + related_udf(name = "rtrim") +)] #[derive(Debug)] pub struct LtrimFunc { signature: Signature, @@ -100,41 +127,10 @@ impl ScalarUDFImpl for LtrimFunc { } fn documentation(&self) -> Option<&Documentation> { - Some(get_ltrim_doc()) + self.doc() } } -static DOCUMENTATION: OnceLock = OnceLock::new(); - -fn get_ltrim_doc() -> &'static Documentation { - DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Trims the specified trim string from the beginning of a string. If no trim string is provided, all whitespace is removed from the start of the input string.") - .with_syntax_example("ltrim(str[, trim_str])") - .with_sql_example(r#"```sql -> select ltrim(' datafusion '); -+-------------------------------+ -| ltrim(Utf8(" datafusion ")) | -+-------------------------------+ -| datafusion | -+-------------------------------+ -> select ltrim('___datafusion___', '_'); -+-------------------------------------------+ -| ltrim(Utf8("___datafusion___"),Utf8("_")) | -+-------------------------------------------+ -| datafusion___ | -+-------------------------------------------+ -```"#) - .with_standard_argument("str", Some("String")) - .with_argument("trim_str", "String expression to trim from the beginning of the input string. Can be a constant, column, or function, and any combination of arithmetic operators. _Default is whitespace characters._") - .with_alternative_syntax("trim(LEADING trim_str FROM str)") - .with_related_udf("btrim") - .with_related_udf("rtrim") - .build() - }) -} - #[cfg(test)] mod tests { use arrow::array::{Array, StringArray, StringViewArray}; diff --git a/datafusion/functions/src/string/octet_length.rs b/datafusion/functions/src/string/octet_length.rs index 08ff9cd07f74..2dbfa6746d61 100644 --- a/datafusion/functions/src/string/octet_length.rs +++ b/datafusion/functions/src/string/octet_length.rs @@ -100,12 +100,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_octet_length_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns the length of a string in bytes.") - .with_syntax_example("octet_length(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns the length of a string in bytes.", + "octet_length(str)", + ) + .with_sql_example( + r#"```sql > select octet_length('Ångström'); +--------------------------------+ | octet_length(Utf8("Ångström")) | @@ -113,11 +114,11 @@ fn get_octet_length_doc() -> &'static Documentation { | 10 | +--------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_related_udf("bit_length") - .with_related_udf("length") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_related_udf("bit_length") + .with_related_udf("length") + .build() }) } diff --git a/datafusion/functions/src/string/overlay.rs b/datafusion/functions/src/string/overlay.rs index 2c62fc467378..ced263456802 100644 --- a/datafusion/functions/src/string/overlay.rs +++ b/datafusion/functions/src/string/overlay.rs @@ -100,10 +100,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_overlay_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns the string which is replaced by another string from the specified position and specified count length.") - .with_syntax_example("overlay(str PLACING substr FROM pos [FOR count])") + Documentation::builder( + DOC_SECTION_STRING, + "Returns the string which is replaced by another string from the specified position and specified count length.", + "overlay(str PLACING substr FROM pos [FOR count])") .with_sql_example(r#"```sql > select overlay('Txxxxas' placing 'hom' from 2 for 4); +--------------------------------------------------------+ diff --git a/datafusion/functions/src/string/repeat.rs b/datafusion/functions/src/string/repeat.rs index 0573a33e7aa9..4140a9b913ff 100644 --- a/datafusion/functions/src/string/repeat.rs +++ b/datafusion/functions/src/string/repeat.rs @@ -89,14 +89,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_repeat_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description( - "Returns a string with an input string repeated a specified number.", - ) - .with_syntax_example("repeat(str, n)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns a string with an input string repeated a specified number.", + "repeat(str, n)", + ) + .with_sql_example( + r#"```sql > select repeat('data', 3); +-------------------------------+ | repeat(Utf8("data"),Int64(3)) | @@ -104,10 +103,10 @@ fn get_repeat_doc() -> &'static Documentation { | datadatadata | +-------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_argument("n", "Number of times to repeat the input string.") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_argument("n", "Number of times to repeat the input string.") + .build() }) } diff --git a/datafusion/functions/src/string/replace.rs b/datafusion/functions/src/string/replace.rs index f561e5757e89..2439799f96d7 100644 --- a/datafusion/functions/src/string/replace.rs +++ b/datafusion/functions/src/string/replace.rs @@ -88,10 +88,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_replace_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Replaces all occurrences of a specified substring in a string with a new substring.") - .with_syntax_example("replace(str, substr, replacement)") + Documentation::builder( + DOC_SECTION_STRING, + "Replaces all occurrences of a specified substring in a string with a new substring.", + "replace(str, substr, replacement)") .with_sql_example(r#"```sql > select replace('ABabbaBA', 'ab', 'cd'); +-------------------------------------------------+ diff --git a/datafusion/functions/src/string/rtrim.rs b/datafusion/functions/src/string/rtrim.rs index 42bd723c6408..b4fe8d432432 100644 --- a/datafusion/functions/src/string/rtrim.rs +++ b/datafusion/functions/src/string/rtrim.rs @@ -108,10 +108,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_rtrim_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Trims the specified trim string from the end of a string. If no trim string is provided, all whitespace is removed from the end of the input string.") - .with_syntax_example("rtrim(str[, trim_str])") + Documentation::builder( + DOC_SECTION_STRING, + "Trims the specified trim string from the end of a string. If no trim string is provided, all whitespace is removed from the end of the input string.", + "rtrim(str[, trim_str])") .with_sql_example(r#"```sql > select rtrim(' datafusion '); +-------------------------------+ diff --git a/datafusion/functions/src/string/split_part.rs b/datafusion/functions/src/string/split_part.rs index ff45c078a4a6..e55325db756d 100644 --- a/datafusion/functions/src/string/split_part.rs +++ b/datafusion/functions/src/string/split_part.rs @@ -190,10 +190,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_split_part_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Splits a string based on a specified delimiter and returns the substring in the specified position.") - .with_syntax_example("split_part(str, delimiter, pos)") + Documentation::builder( + DOC_SECTION_STRING, + "Splits a string based on a specified delimiter and returns the substring in the specified position.", + "split_part(str, delimiter, pos)") .with_sql_example(r#"```sql > select split_part('1.2.3.4.5', '.', 3); +--------------------------------------------------+ diff --git a/datafusion/functions/src/string/starts_with.rs b/datafusion/functions/src/string/starts_with.rs index 104ae843923c..36dbd8167b4e 100644 --- a/datafusion/functions/src/string/starts_with.rs +++ b/datafusion/functions/src/string/starts_with.rs @@ -92,12 +92,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_starts_with_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Tests if a string starts with a substring.") - .with_syntax_example("starts_with(str, substr)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Tests if a string starts with a substring.", + "starts_with(str, substr)", + ) + .with_sql_example( + r#"```sql > select starts_with('datafusion','data'); +----------------------------------------------+ | starts_with(Utf8("datafusion"),Utf8("data")) | @@ -105,10 +106,10 @@ fn get_starts_with_doc() -> &'static Documentation { | true | +----------------------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_argument("substr", "Substring to test for.") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_argument("substr", "Substring to test for.") + .build() }) } diff --git a/datafusion/functions/src/string/to_hex.rs b/datafusion/functions/src/string/to_hex.rs index c56a21aaa121..04907af14ade 100644 --- a/datafusion/functions/src/string/to_hex.rs +++ b/datafusion/functions/src/string/to_hex.rs @@ -124,12 +124,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_to_hex_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Converts an integer to a hexadecimal string.") - .with_syntax_example("to_hex(int)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Converts an integer to a hexadecimal string.", + "to_hex(int)", + ) + .with_sql_example( + r#"```sql > select to_hex(12345689); +-------------------------+ | to_hex(Int64(12345689)) | @@ -137,9 +138,9 @@ fn get_to_hex_doc() -> &'static Documentation { | bc6159 | +-------------------------+ ```"#, - ) - .with_standard_argument("int", Some("Integer")) - .build() + ) + .with_standard_argument("int", Some("Integer")) + .build() }) } diff --git a/datafusion/functions/src/string/upper.rs b/datafusion/functions/src/string/upper.rs index 9e2c7f2f2847..1d05c42394a7 100644 --- a/datafusion/functions/src/string/upper.rs +++ b/datafusion/functions/src/string/upper.rs @@ -78,12 +78,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_upper_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Converts a string to upper-case.") - .with_syntax_example("upper(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Converts a string to upper-case.", + "upper(str)", + ) + .with_sql_example( + r#"```sql > select upper('dataFusion'); +---------------------------+ | upper(Utf8("dataFusion")) | @@ -91,11 +92,11 @@ fn get_upper_doc() -> &'static Documentation { | DATAFUSION | +---------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_related_udf("initcap") - .with_related_udf("lower") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_related_udf("initcap") + .with_related_udf("lower") + .build() }) } diff --git a/datafusion/functions/src/string/uuid.rs b/datafusion/functions/src/string/uuid.rs index eeb1620cdb97..6048a70bd8c5 100644 --- a/datafusion/functions/src/string/uuid.rs +++ b/datafusion/functions/src/string/uuid.rs @@ -88,10 +88,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_uuid_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns [`UUID v4`](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) string value which is unique per row.") - .with_syntax_example("uuid()") + Documentation::builder( + DOC_SECTION_STRING, + "Returns [`UUID v4`](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)) string value which is unique per row.", + "uuid()") .with_sql_example(r#"```sql > select uuid(); +--------------------------------------+ diff --git a/datafusion/functions/src/unicode/character_length.rs b/datafusion/functions/src/unicode/character_length.rs index d8a6ee5278d9..726822a8f887 100644 --- a/datafusion/functions/src/unicode/character_length.rs +++ b/datafusion/functions/src/unicode/character_length.rs @@ -93,12 +93,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_character_length_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns the number of characters in a string.") - .with_syntax_example("character_length(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns the number of characters in a string.", + "character_length(str)", + ) + .with_sql_example( + r#"```sql > select character_length('Ångström'); +------------------------------------+ | character_length(Utf8("Ångström")) | @@ -106,11 +107,11 @@ fn get_character_length_doc() -> &'static Documentation { | 8 | +------------------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .with_related_udf("bit_length") - .with_related_udf("octet_length") - .build() + ) + .with_standard_argument("str", Some("String")) + .with_related_udf("bit_length") + .with_related_udf("octet_length") + .build() }) } diff --git a/datafusion/functions/src/unicode/find_in_set.rs b/datafusion/functions/src/unicode/find_in_set.rs index b00b4205d5eb..38efb408c1d3 100644 --- a/datafusion/functions/src/unicode/find_in_set.rs +++ b/datafusion/functions/src/unicode/find_in_set.rs @@ -93,10 +93,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_find_in_set_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns a value in the range of 1 to N if the string str is in the string list strlist consisting of N substrings.") - .with_syntax_example("find_in_set(str, strlist)") + Documentation::builder( + DOC_SECTION_STRING, + "Returns a value in the range of 1 to N if the string str is in the string list strlist consisting of N substrings.", + "find_in_set(str, strlist)") .with_sql_example(r#"```sql > select find_in_set('b', 'a,b,c,d'); +----------------------------------------+ diff --git a/datafusion/functions/src/unicode/left.rs b/datafusion/functions/src/unicode/left.rs index 486f15f05be1..ef2802340b14 100644 --- a/datafusion/functions/src/unicode/left.rs +++ b/datafusion/functions/src/unicode/left.rs @@ -107,22 +107,25 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_left_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns a specified number of characters from the left side of a string.") - .with_syntax_example("left(str, n)") - .with_sql_example(r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns a specified number of characters from the left side of a string.", + "left(str, n)", + ) + .with_sql_example( + r#"```sql > select left('datafusion', 4); +-----------------------------------+ | left(Utf8("datafusion"),Int64(4)) | +-----------------------------------+ | data | +-----------------------------------+ -```"#) - .with_standard_argument("str", Some("String")) - .with_argument("n", "Number of characters to return.") - .with_related_udf("right") - .build() +```"#, + ) + .with_standard_argument("str", Some("String")) + .with_argument("n", "Number of characters to return.") + .with_related_udf("right") + .build() }) } diff --git a/datafusion/functions/src/unicode/lpad.rs b/datafusion/functions/src/unicode/lpad.rs index 406fe2248665..6c8a4ec97bb0 100644 --- a/datafusion/functions/src/unicode/lpad.rs +++ b/datafusion/functions/src/unicode/lpad.rs @@ -111,10 +111,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_lpad_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Pads the left side of a string with another string to a specified string length.") - .with_syntax_example("lpad(str, n[, padding_str])") + Documentation::builder( + DOC_SECTION_STRING, + "Pads the left side of a string with another string to a specified string length.", + "lpad(str, n[, padding_str])") .with_sql_example(r#"```sql > select lpad('Dolly', 10, 'hello'); +---------------------------------------------+ diff --git a/datafusion/functions/src/unicode/reverse.rs b/datafusion/functions/src/unicode/reverse.rs index b250aa7e23a4..38c1f23cbd5a 100644 --- a/datafusion/functions/src/unicode/reverse.rs +++ b/datafusion/functions/src/unicode/reverse.rs @@ -95,12 +95,13 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_reverse_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Reverses the character order of a string.") - .with_syntax_example("reverse(str)") - .with_sql_example( - r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Reverses the character order of a string.", + "reverse(str)", + ) + .with_sql_example( + r#"```sql > select reverse('datafusion'); +-----------------------------+ | reverse(Utf8("datafusion")) | @@ -108,9 +109,9 @@ fn get_reverse_doc() -> &'static Documentation { | noisufatad | +-----------------------------+ ```"#, - ) - .with_standard_argument("str", Some("String")) - .build() + ) + .with_standard_argument("str", Some("String")) + .build() }) } diff --git a/datafusion/functions/src/unicode/right.rs b/datafusion/functions/src/unicode/right.rs index 13be9297b197..1586e23eb8aa 100644 --- a/datafusion/functions/src/unicode/right.rs +++ b/datafusion/functions/src/unicode/right.rs @@ -107,22 +107,25 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_right_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns a specified number of characters from the right side of a string.") - .with_syntax_example("right(str, n)") - .with_sql_example(r#"```sql + Documentation::builder( + DOC_SECTION_STRING, + "Returns a specified number of characters from the right side of a string.", + "right(str, n)", + ) + .with_sql_example( + r#"```sql > select right('datafusion', 6); +------------------------------------+ | right(Utf8("datafusion"),Int64(6)) | +------------------------------------+ | fusion | +------------------------------------+ -```"#) - .with_standard_argument("str", Some("String")) - .with_argument("n", "Number of characters to return") - .with_related_udf("left") - .build() +```"#, + ) + .with_standard_argument("str", Some("String")) + .with_argument("n", "Number of characters to return") + .with_related_udf("left") + .build() }) } diff --git a/datafusion/functions/src/unicode/rpad.rs b/datafusion/functions/src/unicode/rpad.rs index a574cb8515d5..6e6bde3e177c 100644 --- a/datafusion/functions/src/unicode/rpad.rs +++ b/datafusion/functions/src/unicode/rpad.rs @@ -130,10 +130,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_rpad_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Pads the right side of a string with another string to a specified string length.") - .with_syntax_example("rpad(str, n[, padding_str])") + Documentation::builder( + DOC_SECTION_STRING, + "Pads the right side of a string with another string to a specified string length.", + "rpad(str, n[, padding_str])") .with_sql_example(r#"```sql > select rpad('datafusion', 20, '_-'); +-----------------------------------------------+ diff --git a/datafusion/functions/src/unicode/strpos.rs b/datafusion/functions/src/unicode/strpos.rs index 3d8b97fc9bb1..1917cd7291cc 100644 --- a/datafusion/functions/src/unicode/strpos.rs +++ b/datafusion/functions/src/unicode/strpos.rs @@ -87,10 +87,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_strpos_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Returns the starting position of a specified substring in a string. Positions begin at 1. If the substring does not exist in the string, the function returns 0.") - .with_syntax_example("strpos(str, substr)") + Documentation::builder( + DOC_SECTION_STRING, + "Returns the starting position of a specified substring in a string. Positions begin at 1. If the substring does not exist in the string, the function returns 0.", + "strpos(str, substr)") .with_sql_example(r#"```sql > select strpos('datafusion', 'fus'); +----------------------------------------+ diff --git a/datafusion/functions/src/unicode/substr.rs b/datafusion/functions/src/unicode/substr.rs index 193210fa0b77..0ac050c707bf 100644 --- a/datafusion/functions/src/unicode/substr.rs +++ b/datafusion/functions/src/unicode/substr.rs @@ -162,10 +162,10 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_substr_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Extracts a substring of a specified number of characters from a specific starting position in a string.") - .with_syntax_example("substr(str, start_pos[, length])") + Documentation::builder( + DOC_SECTION_STRING, + "Extracts a substring of a specified number of characters from a specific starting position in a string.", + "substr(str, start_pos[, length])") .with_sql_example(r#"```sql > select substr('datafusion', 5, 3); +----------------------------------------------+ diff --git a/datafusion/functions/src/unicode/substrindex.rs b/datafusion/functions/src/unicode/substrindex.rs index b6a7faddeb21..825666b0455e 100644 --- a/datafusion/functions/src/unicode/substrindex.rs +++ b/datafusion/functions/src/unicode/substrindex.rs @@ -99,12 +99,12 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_substr_index_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description(r#"Returns the substring from str before count occurrences of the delimiter delim. + Documentation::builder( + DOC_SECTION_STRING, + r#"Returns the substring from str before count occurrences of the delimiter delim. If count is positive, everything to the left of the final delimiter (counting from the left) is returned. -If count is negative, everything to the right of the final delimiter (counting from the right) is returned."#) - .with_syntax_example("substr_index(str, delim, count)") +If count is negative, everything to the right of the final delimiter (counting from the right) is returned."#, + "substr_index(str, delim, count)") .with_sql_example(r#"```sql > select substr_index('www.apache.org', '.', 1); +---------------------------------------------------------+ diff --git a/datafusion/functions/src/unicode/translate.rs b/datafusion/functions/src/unicode/translate.rs index f3bf6f6564cf..780603777133 100644 --- a/datafusion/functions/src/unicode/translate.rs +++ b/datafusion/functions/src/unicode/translate.rs @@ -93,10 +93,7 @@ static DOCUMENTATION: OnceLock = OnceLock::new(); fn get_translate_doc() -> &'static Documentation { DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DOC_SECTION_STRING) - .with_description("Translates characters in a string to specified translation characters.") - .with_syntax_example("translate(str, chars, translation)") + Documentation::builder(DOC_SECTION_STRING,"Translates characters in a string to specified translation characters.","translate(str, chars, translation)") .with_sql_example(r#"```sql > select translate('twice', 'wic', 'her'); +--------------------------------------------------+ diff --git a/datafusion/macros/src/lib.rs b/datafusion/macros/src/lib.rs index 319f1f209a0d..e4eeeba7a4ab 100644 --- a/datafusion/macros/src/lib.rs +++ b/datafusion/macros/src/lib.rs @@ -62,12 +62,12 @@ use syn::{parse_macro_input, DeriveInput, LitStr}; /// Some(DOCUMENTATION.get_or_init(|| /// { /// Documentation :: -/// builder().with_doc_section(DocSection +/// builder(DocSection /// { /// include : true, label : "Time and Date Functions", description /// : None -/// }).with_description(r"Converts a value to a date (`YYYY-MM-DD`).") -/// .with_syntax_example("to_date('2017-05-31', '%Y-%m-%d')".to_string()).with_sql_example("```sql\n\ +/// }, r"Converts a value to a date (`YYYY-MM-DD`).") +/// .with_syntax_example("to_date('2017-05-31', '%Y-%m-%d')".to_string(),"```sql\n\ /// \> select to_date('2023-01-31');\n\ /// +-----------------------------+\n\ /// | to_date(Utf8(\"2023-01-31\")) |\n\ @@ -90,9 +90,11 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { let mut description: Option = None; let mut syntax_example: Option = None; + let mut alt_syntax_example: Option = None; let mut sql_example: Option = None; let mut standard_args: Vec<(Option, Option)> = vec![]; let mut udf_args: Vec<(Option, Option)> = vec![]; + let mut related_udfs: Vec> = vec![]; let parser = syn::meta::parser(|meta| { if meta.path.is_ident("doc_section") { @@ -115,6 +117,9 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { } else if meta.path.is_ident("syntax_example") { syntax_example = Some(meta.value()?.parse()?); Ok(()) + } else if meta.path.is_ident("alternative_syntax") { + alt_syntax_example = Some(meta.value()?.parse()?); + Ok(()) } else if meta.path.is_ident("sql_example") { sql_example = Some(meta.value()?.parse()?); Ok(()) @@ -149,9 +154,22 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { udf_args.push(arg.clone()); + m + } else if meta.path.is_ident("related_udf") { + let mut arg: Option = None; + let m = meta.parse_nested_meta(|meta| { + if meta.path.is_ident("name") { + arg = meta.value()?.parse()?; + return Ok(()); + } + Ok(()) + }); + + related_udfs.push(arg.clone()); + m } else { - Err(meta.error(format!("Unsupported property {:?}", meta.path.get_ident()))) + Err(meta.error(format!("Unsupported property: {:?}", meta.path.get_ident()))) } }); @@ -161,7 +179,13 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { let input = parse_macro_input!(input as DeriveInput); let name = input.clone().ident; - let doc_section_include: bool = doc_section_include.unwrap().value().parse().unwrap(); + let doc_section_include: bool = if let Some(doc_section_include) = doc_section_include + { + doc_section_include.value().parse().unwrap() + } else { + true + }; + let doc_section_description = doc_section_desc .map(|desc| quote! { Some(#desc)}) .unwrap_or(quote! { None }); @@ -184,6 +208,21 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { }) .collect::>(); + let related_udfs = related_udfs + .iter() + .map(|name| { + quote! { + .with_related_udf(#name) + } + }) + .collect::>(); + + let alt_syntax_example = alt_syntax_example.map(|syn| { + quote! { + .with_alternative_syntax(#syn) + } + }); + let generated = quote! { #input @@ -195,13 +234,13 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { impl #name { fn doc(&self) -> Option<&Documentation> { Some(DOCUMENTATION.get_or_init(|| { - Documentation::builder() - .with_doc_section(DocSection { include: #doc_section_include, label: #doc_section_lbl, description: #doc_section_description }) - .with_description(#description.to_string()) - .with_syntax_example(#syntax_example.to_string()) + Documentation::builder(DocSection { include: #doc_section_include, label: #doc_section_lbl, description: #doc_section_description }, + #description.to_string(), #syntax_example.to_string()) .with_sql_example(#sql_example.to_string()) + #alt_syntax_example #(#standard_args)* #(#udf_args)* + #(#related_udfs)* .build() })) } @@ -209,7 +248,7 @@ pub fn user_doc(args: TokenStream, input: TokenStream) -> TokenStream { }; // Debug the generated code if needed - // eprintln!("Generated code: {}", generated); + //eprintln!("Generated code: {}", generated); // Return the generated code TokenStream::from(generated)