From 030c4e942332d716c9eabfb9297b4c75fe572377 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Sat, 5 Oct 2024 06:12:40 -0400 Subject: [PATCH] Add `DocumentationBuilder::with_standard_argument` to reduce copy/paste (#12747) * Add `DocumentationBuilder::with_standard_expression` to reduce copy/paste * fix doc * fix standard argument * Update docs * Improve documentation to explain what is different --- datafusion/expr/src/udf_docs.rs | 24 +++++++++++++++++++ .../functions-aggregate/src/bit_and_or_xor.rs | 19 +++++---------- datafusion/functions/src/crypto/sha224.rs | 3 +-- datafusion/functions/src/datetime/to_date.rs | 5 +--- datafusion/functions/src/math/log.rs | 6 ++--- datafusion/functions/src/regex/regexplike.rs | 6 ++--- datafusion/functions/src/unicode/rpad.rs | 4 ++-- .../user-guide/sql/aggregate_functions_new.md | 6 ++--- .../user-guide/sql/scalar_functions_new.md | 14 +++++------ 9 files changed, 48 insertions(+), 39 deletions(-) diff --git a/datafusion/expr/src/udf_docs.rs b/datafusion/expr/src/udf_docs.rs index 280910b87199..e8245588d945 100644 --- a/datafusion/expr/src/udf_docs.rs +++ b/datafusion/expr/src/udf_docs.rs @@ -131,6 +131,9 @@ impl DocumentationBuilder { self } + /// Adds documentation for a specific argument to the documentation. + /// + /// Arguments are displayed in the order they are added. pub fn with_argument( mut self, arg_name: impl Into, @@ -142,6 +145,27 @@ impl DocumentationBuilder { self } + /// Add a standard "expression" argument to the documentation + /// + /// This is similar to [`Self::with_argument`] except that a standard + /// description is appended to the end: `"Can be a constant, column, or + /// function, and any combination of arithmetic operators."` + /// + /// The argument is rendered like + /// + /// ```text + /// : + /// expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. + /// ``` + pub fn with_standard_argument( + self, + arg_name: impl Into, + expression_type: impl AsRef, + ) -> Self { + let expression_type = expression_type.as_ref(); + self.with_argument(arg_name, format!("{expression_type} expression to operate on. Can be a constant, column, or function, and any combination of operators.")) + } + pub fn with_related_udf(mut self, related_udf: impl Into) -> Self { let mut related = self.related_udfs.unwrap_or_default(); related.push(related_udf.into()); diff --git a/datafusion/functions-aggregate/src/bit_and_or_xor.rs b/datafusion/functions-aggregate/src/bit_and_or_xor.rs index ce36e09bc25b..c5382c168f17 100644 --- a/datafusion/functions-aggregate/src/bit_and_or_xor.rs +++ b/datafusion/functions-aggregate/src/bit_and_or_xor.rs @@ -142,10 +142,7 @@ fn get_bit_and_doc() -> &'static Documentation { .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_argument( - "expression", - "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.", - ) + .with_standard_argument("expression", "Integer") .build() .unwrap() }) @@ -159,10 +156,7 @@ fn get_bit_or_doc() -> &'static Documentation { .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_argument( - "expression", - "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.", - ) + .with_standard_argument("expression", "Integer") .build() .unwrap() }) @@ -174,12 +168,11 @@ 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_argument( - "expression", - "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.", + .with_description( + "Computes the bitwise exclusive OR of all non-null input values.", ) + .with_syntax_example("bit_xor(expression)") + .with_standard_argument("expression", "Integer") .build() .unwrap() }) diff --git a/datafusion/functions/src/crypto/sha224.rs b/datafusion/functions/src/crypto/sha224.rs index df3045f22cf5..d603e5bcf295 100644 --- a/datafusion/functions/src/crypto/sha224.rs +++ b/datafusion/functions/src/crypto/sha224.rs @@ -58,8 +58,7 @@ fn get_sha224_doc() -> &'static Documentation { .with_doc_section(DOC_SECTION_HASHING) .with_description("Computes the SHA-224 hash of a binary string.") .with_syntax_example("sha224(expression)") - .with_argument("expression", - "String expression to operate on. Can be a constant, column, or function, and any combination of string operators.") + .with_standard_argument("expression", "String") .build() .unwrap() }) diff --git a/datafusion/functions/src/datetime/to_date.rs b/datafusion/functions/src/datetime/to_date.rs index 176d7f8bbcbf..2803fd042b99 100644 --- a/datafusion/functions/src/datetime/to_date.rs +++ b/datafusion/functions/src/datetime/to_date.rs @@ -111,10 +111,7 @@ Note: `to_date` returns Date32, which represents its values as the number of day Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/to_date.rs) "#) - .with_argument( - "expression", - "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.", - ) + .with_standard_argument("expression", "String") .with_argument( "format_n", "Optional [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) strings to use to parse the expression. Formats will be tried in the order diff --git a/datafusion/functions/src/math/log.rs b/datafusion/functions/src/math/log.rs index 889e3761d26c..07ff8e2166ff 100644 --- a/datafusion/functions/src/math/log.rs +++ b/datafusion/functions/src/math/log.rs @@ -57,10 +57,8 @@ fn get_log_doc() -> &'static Documentation { .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) log(numeric_expression)"#) - .with_argument("base", - "Base numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.") - .with_argument("numeric_expression", - "Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.") + .with_standard_argument("base", "Base numeric") + .with_standard_argument("numeric_expression", "Numeric") .build() .unwrap() }) diff --git a/datafusion/functions/src/regex/regexplike.rs b/datafusion/functions/src/regex/regexplike.rs index 2abb4a9376c5..f647b1969168 100644 --- a/datafusion/functions/src/regex/regexplike.rs +++ b/datafusion/functions/src/regex/regexplike.rs @@ -67,10 +67,8 @@ SELECT regexp_like('aBc', '(b|d)', 'i'); ``` Additional examples can be found [here](https://github.com/apache/datafusion/blob/main/datafusion-examples/examples/regexp.rs) "#) - .with_argument("str", - "String expression to operate on. Can be a constant, column, or function, and any combination of string operators.") - .with_argument("regexp", - "Regular expression to test against the string expression. Can be a constant, column, or function.") + .with_standard_argument("str", "String") + .with_standard_argument("regexp","Regular") .with_argument("flags", r#"Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: - **i**: case-insensitive: letters match both upper and lower case diff --git a/datafusion/functions/src/unicode/rpad.rs b/datafusion/functions/src/unicode/rpad.rs index ce221b44f42b..05ecff05a179 100644 --- a/datafusion/functions/src/unicode/rpad.rs +++ b/datafusion/functions/src/unicode/rpad.rs @@ -55,9 +55,9 @@ fn get_rpad_doc() -> &'static Documentation { .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])") - .with_argument( + .with_standard_argument( "str", - "String expression to operate on. Can be a constant, column, or function, and any combination of string operators.", + "String", ) .with_argument("n", "String length to pad to.") .with_argument("padding_str", diff --git a/docs/source/user-guide/sql/aggregate_functions_new.md b/docs/source/user-guide/sql/aggregate_functions_new.md index 8303c50c2471..2c8ebc3be990 100644 --- a/docs/source/user-guide/sql/aggregate_functions_new.md +++ b/docs/source/user-guide/sql/aggregate_functions_new.md @@ -47,7 +47,7 @@ bit_and(expression) #### Arguments -- **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. ### `bit_or` @@ -59,7 +59,7 @@ bit_or(expression) #### Arguments -- **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. ### `bit_xor` @@ -71,4 +71,4 @@ bit_xor(expression) #### Arguments -- **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression**: Integer expression to operate on. Can be a constant, column, or function, and any combination of operators. diff --git a/docs/source/user-guide/sql/scalar_functions_new.md b/docs/source/user-guide/sql/scalar_functions_new.md index ae2744c1650e..bff2c0f485c3 100644 --- a/docs/source/user-guide/sql/scalar_functions_new.md +++ b/docs/source/user-guide/sql/scalar_functions_new.md @@ -44,8 +44,8 @@ log(numeric_expression) #### Arguments -- **base**: Base numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. -- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +- **base**: Base numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **numeric_expression**: Numeric expression to operate on. Can be a constant, column, or function, and any combination of operators. ## Conditional Functions @@ -94,7 +94,7 @@ rpad(str, n[, padding_str]) #### Arguments -- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. - **n**: String length to pad to. - **padding_str**: String expression to pad with. Can be a constant, column, or function, and any combination of string operators. _Default is a space._ @@ -160,8 +160,8 @@ regexp_like(str, regexp[, flags]) #### Arguments -- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. -- **regexp**: Regular expression to test against the string expression. Can be a constant, column, or function. +- **str**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. +- **regexp**: Regular expression to operate on. Can be a constant, column, or function, and any combination of operators. - **flags**: Optional regular expression flags that control the behavior of the regular expression. The following flags are supported: - **i**: case-insensitive: letters match both upper and lower case - **m**: multi-line mode: ^ and $ match begin/end of line @@ -208,7 +208,7 @@ to_date('2017-05-31', '%Y-%m-%d') #### Arguments -- **expression**: Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators. +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators. - **format_n**: Optional [Chrono format](https://docs.rs/chrono/latest/chrono/format/strftime/index.html) strings to use to parse the expression. Formats will be tried in the order they appear with the first successful one being returned. If none of the formats successfully parse the expression an error will be returned. @@ -246,4 +246,4 @@ sha224(expression) #### Arguments -- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of string operators. +- **expression**: String expression to operate on. Can be a constant, column, or function, and any combination of operators.