Refactored Documentation to allow it to be used in a const.

apache · Sep 29, 2024 · bcf5a76 · bcf5a76
1 parent 0c4bde3
commit bcf5a76
Show file tree

Hide file tree

Showing 20 changed files with 295 additions and 305 deletions.
diff --git a/datafusion-cli/Cargo.lock b/datafusion-cli/Cargo.lock
diff --git a/datafusion/core/src/bin/print_aggregate_functions_docs.rs b/datafusion/core/src/bin/print_aggregate_functions_docs.rs
@@ -92,7 +92,7 @@ fn main() {
             );
 
             // next, arguments
-            if let Some(args) = &documentation.arguments {
+            if let Some(args) = documentation.arguments {
                 let _ = writeln!(&mut docs, "#### Arguments\n");
                 for (arg_name, arg_desc) in args {
                     let _ = writeln!(&mut docs, "- **{arg_name}**: {arg_desc}");
@@ -122,7 +122,7 @@ fn main() {
             }
 
             // finally, any related udfs
-            if let Some(related_udfs) = &documentation.related_udfs {
+            if let Some(related_udfs) = documentation.related_udfs {
                 let _ = writeln!(&mut docs, "\n**Related functions**:");
 
                 for related in related_udfs {

diff --git a/datafusion/core/src/bin/print_scalar_functions_docs.rs b/datafusion/core/src/bin/print_scalar_functions_docs.rs
@@ -92,7 +92,7 @@ fn main() {
             );
 
             // next, arguments
-            if let Some(args) = &documentation.arguments {
+            if let Some(args) = documentation.arguments {
                 let _ = writeln!(&mut docs, "#### Arguments\n");
                 for (arg_name, arg_desc) in args {
                     let _ = writeln!(&mut docs, "- **{arg_name}**: {arg_desc}");
@@ -122,7 +122,7 @@ fn main() {
             }
 
             // finally, any related udfs
-            if let Some(related_udfs) = &documentation.related_udfs {
+            if let Some(related_udfs) = documentation.related_udfs {
                 let _ = writeln!(&mut docs, "\n**Related functions**:");
 
                 for related in related_udfs {

diff --git a/datafusion/core/src/bin/print_window_functions_docs.rs b/datafusion/core/src/bin/print_window_functions_docs.rs
@@ -92,7 +92,7 @@ fn main() {
             );
 
             // next, arguments
-            if let Some(args) = &documentation.arguments {
+            if let Some(args) = documentation.arguments {
                 let _ = writeln!(&mut docs, "#### Arguments\n");
                 for (arg_name, arg_desc) in args {
                     let _ = writeln!(&mut docs, "- **{arg_name}**: {arg_desc}");
@@ -122,10 +122,10 @@ fn main() {
             }
 
             // finally, any related udfs
-            if let Some(related_udfs) = &documentation.related_udfs {
+            if let Some(related_udfs) = documentation.related_udfs {
                 let _ = writeln!(&mut docs, "\n**Related functions**:");
 
-                for related in related_udfs {
+                for &related in related_udfs {
                     let _ = writeln!(&mut docs, "- [{related}](#{related})");
                 }
             }

diff --git a/datafusion/expr/Cargo.toml b/datafusion/expr/Cargo.toml
@@ -48,7 +48,6 @@ datafusion-expr-common = { workspace = true }
 datafusion-functions-aggregate-common = { workspace = true }
 datafusion-functions-window-common = { workspace = true }
 datafusion-physical-expr-common = { workspace = true }
-indexmap = { workspace = true }
 paste = "^1.0"
 serde_json = { workspace = true }
 sqlparser = { workspace = true }

diff --git a/datafusion/expr/src/udaf.rs b/datafusion/expr/src/udaf.rs
@@ -285,30 +285,29 @@ where
 /// # use datafusion_expr::window_doc_sections::DOC_SECTION_AGGREGATE;
 /// # use arrow::datatypes::Schema;
 /// # use arrow::datatypes::Field;
-/// # use indexmap::IndexMap;
 ///
 /// #[derive(Debug, Clone)]
 /// struct GeoMeanUdf {
 ///   signature: Signature,
-///   documentation: Documentation,
 /// }
 ///
 /// impl GeoMeanUdf {
 ///   fn new() -> Self {
 ///     Self {
 ///       signature: Signature::uniform(1, vec![DataType::Float64], Volatility::Immutable),
-///       documentation: Documentation {
-///             doc_section: DOC_SECTION_AGGREGATE,
-///             description: "calculates a geometric mean",
-///             syntax_example: "geo_mean(2.0)",
-///             sql_example: None,    
-///             arguments: Some(IndexMap::from([("arg_1", "The Float64 number for the geometric mean")])),
-///             related_udfs: None,
-///         }    
 ///      }
 ///   }
 /// }
 ///
+/// const DOCUMENTATION: Documentation = Documentation {
+///     doc_section: DOC_SECTION_AGGREGATE,
+///     description: "calculates a geometric mean",
+///     syntax_example: "geo_mean(2.0)",
+///     sql_example: None,    
+///     arguments: Some(&[("arg_1", "The Float64 number for the geometric mean")]),
+///     related_udfs: None,
+/// };
+///    
 /// /// Implement the AggregateUDFImpl trait for GeoMeanUdf
 /// impl AggregateUDFImpl for GeoMeanUdf {
 ///    fn as_any(&self) -> &dyn Any { self }
@@ -329,7 +328,7 @@ where
 ///        ])
 ///    }
 ///    fn documentation(&self) -> &Documentation {
-///        &self.documentation  
+///        &DOCUMENTATION  
 ///    }
 /// }
 ///

diff --git a/datafusion/expr/src/udf.rs b/datafusion/expr/src/udf.rs
@@ -307,7 +307,6 @@ where
 /// ```
 /// # use std::any::Any;
 /// # use arrow::datatypes::DataType;
-/// # use indexmap::IndexMap;
 /// # use datafusion_common::{DataFusionError, plan_err, Result};
 /// # use datafusion_expr::{col, ColumnarValue, Documentation, Signature, Volatility};
 /// # use datafusion_expr::{ScalarUDFImpl, ScalarUDF};
@@ -316,25 +315,25 @@ where
 /// #[derive(Debug)]
 /// struct AddOne {
 ///   signature: Signature,
-///   documentation: Documentation,
 /// }
 ///
 /// impl AddOne {
 ///   fn new() -> Self {
 ///     Self {
 ///       signature: Signature::uniform(1, vec![DataType::Int32], Volatility::Immutable),
-///       documentation: Documentation {
-///             doc_section: DOC_SECTION_MATH,
-///             description: "Add one to an int32",
-///             syntax_example: "add_one(2)",
-///             sql_example: None,    
-///             arguments: Some(IndexMap::from([("arg_1", "The int32 number to add one to")])),
-///             related_udfs: None,
-///         }     
 ///      }
 ///   }
 /// }
-///
+///  
+/// const DOCUMENTATION: Documentation = Documentation {
+///     doc_section: DOC_SECTION_MATH,
+///     description: "Add one to an int32",
+///     syntax_example: "add_one(2)",
+///     sql_example: None,    
+///     arguments: Some(&[("arg_1", "The int32 number to add one to")]),
+///     related_udfs: None,
+/// };
+///     
 /// /// Implement the ScalarUDFImpl trait for AddOne
 /// impl ScalarUDFImpl for AddOne {
 ///    fn as_any(&self) -> &dyn Any { self }
@@ -349,7 +348,7 @@ where
 ///    // The actual implementation would add one to the argument
 ///    fn invoke(&self, args: &[ColumnarValue]) -> Result<ColumnarValue> { unimplemented!() }
 ///    fn documentation(&self) -> &Documentation {
-///         &self.documentation
+///         &DOCUMENTATION
 ///     }
 /// }
 ///

diff --git a/datafusion/expr/src/udf_docs.rs b/datafusion/expr/src/udf_docs.rs
@@ -15,8 +15,6 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use indexmap::IndexMap;
-
 /// Documentation for use by [`crate::ScalarUDFImpl`],
 /// [`crate::AggregateUDFImpl`] and [`crate::WindowUDFImpl`] functions
 /// that will be used to generate public documentation.
@@ -41,15 +39,15 @@ pub struct Documentation {
     /// query and output. It is strongly recommended to provide an
     /// example for anything but the most basic UDF's
     pub sql_example: Option<&'static str>,
-    /// arguments for the UDF which will be displayed in insertion
-    /// order. Key is the argument name, value is a description for
-    /// the argument
-    pub arguments: Option<IndexMap<&'static str, &'static str>>,
+    /// arguments for the UDF which will be displayed in array order.
+    /// Left member of a pair is the argument name, right is a
+    /// description for the argument
+    pub arguments: Option<&'static [(&'static str, &'static str)]>,
     /// related functions if any. Values should match the related
     /// udf's name exactly. Related udf's must be of the same
     /// UDF type (scalar, aggregate or window) for proper linking to
     /// occur
-    pub related_udfs: Option<Vec<&'static str>>,
+    pub related_udfs: Option<&'static [&'static str]>,
 }
 
 #[derive(Debug, Clone, PartialEq)]

diff --git a/datafusion/expr/src/udwf.rs b/datafusion/expr/src/udwf.rs
@@ -217,30 +217,29 @@ where
 /// # use datafusion_expr::{WindowUDFImpl, WindowUDF};
 /// # use datafusion_expr::window_doc_sections::DOC_SECTION_ANALYTICAL;
 /// # use datafusion_functions_window_common::field::WindowUDFFieldArgs;
-/// # use indexmap::IndexMap;
 ///
 /// #[derive(Debug, Clone)]
 /// struct SmoothIt {
 ///   signature: Signature,
-///   documentation: Documentation,
 /// }
 ///
 /// impl SmoothIt {
 ///   fn new() -> Self {
 ///     Self {
 ///       signature: Signature::uniform(1, vec![DataType::Int32], Volatility::Immutable),
-///       documentation: Documentation {
-///             doc_section: DOC_SECTION_ANALYTICAL,
-///             description: "smooths the windows",
-///             syntax_example: "smooth_it(2)",
-///             sql_example: None,
-///             arguments: Some(IndexMap::from([("arg_1", "The int32 number to smooth by")])),
-///             related_udfs: None,
-///         }
 ///      }
 ///   }
 /// }
 ///
+/// const DOCUMENTATION: Documentation = Documentation {
+///     doc_section: DOC_SECTION_ANALYTICAL,
+///     description: "smooths the windows",
+///     syntax_example: "smooth_it(2)",
+///     sql_example: None,
+///     arguments: Some(&[("arg_1", "The int32 number to smooth by")]),
+///     related_udfs: None,
+/// };
+
 /// /// Implement the WindowUDFImpl trait for SmoothIt
 /// impl WindowUDFImpl for SmoothIt {
 ///    fn as_any(&self) -> &dyn Any { self }
@@ -256,7 +255,7 @@ where
 ///      }
 ///    }
 ///    fn documentation(&self) -> &Documentation {
-///      &self.documentation
+///      &DOCUMENTATION
 ///    }
 /// }
 ///

diff --git a/datafusion/functions-aggregate/src/bit_and_or_xor.rs b/datafusion/functions-aggregate/src/bit_and_or_xor.rs
@@ -17,7 +17,6 @@
 
 //! Defines `BitAnd`, `BitOr`, `BitXor` and `BitXor DISTINCT` aggregate accumulators
 
-use indexmap::IndexMap;
 use std::any::Any;
 use std::collections::HashSet;
 use std::fmt::{Display, Formatter};
@@ -134,59 +133,65 @@ macro_rules! make_bitwise_udaf_expr_and_func {
     };
 }
 
+const BIT_AND_DOC: Documentation = Documentation {
+    doc_section: DOC_SECTION_GENERAL,
+    description: "Computes the bitwise AND of all non-null input values.",
+    syntax_example: "bit_and(expression)",
+    sql_example: None,
+    arguments: Some(&[
+        (
+            "expression",
+            "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.",
+        ),
+    ]),
+    related_udfs: None,
+};
+
+const BIT_OR_DOC: Documentation = Documentation {
+    doc_section: DOC_SECTION_GENERAL,
+    description: "Computes the bitwise OR of all non-null input values.",
+    syntax_example: "bit_or(expression)",
+    sql_example: None,
+    arguments: Some(&[
+        (
+            "expression",
+            "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.",
+        ),
+    ]),
+    related_udfs: None,
+};
+
+const BIT_XOR_DOC: Documentation =  Documentation {
+    doc_section: DOC_SECTION_GENERAL,
+    description: "Computes the bitwise exclusive OR of all non-null input values.",
+    syntax_example: "bit_xor(expression)",
+    sql_example: None,
+    arguments: Some(&[
+        (
+            "expression",
+            "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.",
+        ),
+    ]),
+    related_udfs: None,
+};
+
 make_bitwise_udaf_expr_and_func!(
     bit_and,
     bit_and_udaf,
     BitwiseOperationType::And,
-    Documentation {
-        doc_section: DOC_SECTION_GENERAL,
-        description: "Computes the bitwise AND of all non-null input values.",
-        syntax_example: "bit_and(expression)",
-        sql_example: None,
-        arguments: Some(IndexMap::from([
-            (
-                "expression",
-                "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.",
-            ),
-        ])),
-        related_udfs: None,
-    }
+    BIT_AND_DOC
 );
 make_bitwise_udaf_expr_and_func!(
     bit_or,
     bit_or_udaf,
     BitwiseOperationType::Or,
-    Documentation {
-        doc_section: DOC_SECTION_GENERAL,
-        description: "Computes the bitwise OR of all non-null input values.",
-        syntax_example: "bit_or(expression)",
-        sql_example: None,
-        arguments: Some(IndexMap::from([
-            (
-                "expression",
-                "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.",
-            ),
-        ])),
-        related_udfs: None,
-    }
+    BIT_OR_DOC
 );
 make_bitwise_udaf_expr_and_func!(
     bit_xor,
     bit_xor_udaf,
     BitwiseOperationType::Xor,
-    Documentation {
-        doc_section: DOC_SECTION_GENERAL,
-        description: "Computes the bitwise exclusive OR of all non-null input values.",
-        syntax_example: "bit_xor(expression)",
-        sql_example: None,
-        arguments: Some(IndexMap::from([
-            (
-                "expression",
-                "Expression to operate on. Can be a constant, column, or function, and any combination of arithmetic operators.",
-            ),
-        ])),
-        related_udfs: None,
-    }
+    BIT_XOR_DOC
 );
 
 /// The different types of bitwise operations that can be performed.