Add DocumentationBuilder::with_standard_argument to reduce copy/pas…

…te (#12747) * Add `DocumentationBuilder::with_standard_expression` to reduce copy/paste * fix doc * fix standard argument * Update docs * Improve documentation to explain what is different
apache · Oct 5, 2024 · 030c4e9 · 030c4e9
1 parent 8aafa54
commit 030c4e9
Show file tree

Hide file tree

Showing 9 changed files with 48 additions and 39 deletions.
diff --git 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<String>,
@@ -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
+    /// <arg_name>:
+    ///   <expression_type> 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<String>,
+        expression_type: impl AsRef<str>,
+    ) -> 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<String>) -> 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.