From 97a8ef4be83dd20dd043a2def220d330b69bf453 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 20 Dec 2024 22:07:57 -0500 Subject: [PATCH 1/4] Fix build --- datafusion/sql/src/statement.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/datafusion/sql/src/statement.rs b/datafusion/sql/src/statement.rs index e934e5d3ca8c..4fa359ebe00d 100644 --- a/datafusion/sql/src/statement.rs +++ b/datafusion/sql/src/statement.rs @@ -62,8 +62,8 @@ use sqlparser::ast::{ Assignment, AssignmentTarget, ColumnDef, CreateIndex, CreateTable, CreateTableOptions, Delete, DescribeAlias, Expr as SQLExpr, FromTable, Ident, Insert, ObjectName, ObjectType, OneOrManyWithParens, Query, SchemaName, SetExpr, - ShowCreateObject, Statement, TableConstraint, TableFactor, TableWithJoins, - TransactionMode, UnaryOperator, Value, + ShowCreateObject, ShowStatementFilter, Statement, TableConstraint, TableFactor, + TableWithJoins, TransactionMode, UnaryOperator, Value, }; use sqlparser::parser::ParserError::ParserError; From 6eb98cc5221004f99858f2fbdafb80d60053e4bc Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 20 Dec 2024 22:21:59 -0500 Subject: [PATCH 2/4] Restore DocBuilder::new(), deprecate --- datafusion/doc/src/lib.rs | 34 +++++++++++++++++++++++++++++----- 1 file changed, 29 insertions(+), 5 deletions(-) diff --git a/datafusion/doc/src/lib.rs b/datafusion/doc/src/lib.rs index 3d8fae6cd32b..371dcf1eea17 100644 --- a/datafusion/doc/src/lib.rs +++ b/datafusion/doc/src/lib.rs @@ -17,9 +17,11 @@ #[allow(rustdoc::broken_intra_doc_links)] /// Documentation for use by [`ScalarUDFImpl`](ScalarUDFImpl), -/// [`AggregateUDFImpl`](AggregateUDFImpl) and [`WindowUDFImpl`](WindowUDFImpl) functions -/// that will be used to generate public documentation. +/// [`AggregateUDFImpl`](AggregateUDFImpl) and [`WindowUDFImpl`](WindowUDFImpl) functions. /// +/// See the [`DocumentationBuilder`] to create a new [`Documentation`] struct. +/// +/// The DataFusion [SQL function documentation] is automatically generated from these structs. /// The name of the udf will be pulled from the [`ScalarUDFImpl::name`](ScalarUDFImpl::name), /// [`AggregateUDFImpl::name`](AggregateUDFImpl::name) or [`WindowUDFImpl::name`](WindowUDFImpl::name) /// function as appropriate. @@ -29,6 +31,8 @@ /// /// Currently, documentation only supports a single language /// thus all text should be in English. +/// +/// [SQL function documentation]: https://datafusion.apache.org/user-guide/sql/index.html #[derive(Debug, Clone)] pub struct Documentation { /// The section in the documentation where the UDF will be documented @@ -61,7 +65,7 @@ impl Documentation { description: impl Into, syntax_example: impl Into, ) -> DocumentationBuilder { - DocumentationBuilder::new(doc_section, description, syntax_example) + DocumentationBuilder::new_with_details(doc_section, description, syntax_example) } /// Output the `Documentation` struct in form of custom Rust documentation attributes @@ -160,7 +164,21 @@ pub struct DocSection { pub description: Option<&'static str>, } -/// A builder to be used for building [`Documentation`]'s. +impl Default for DocSection { + /// Returns a "default" Doc section. + /// + /// This is suitable for user defined functions that do not appear in the + /// DataFusion documentation. + fn default() -> Self { + Self { + include: true, + label: "Default", + description: None, + } + } +} + +/// A builder for [`Documentation`]'s. /// /// Example: /// @@ -189,7 +207,13 @@ pub struct DocumentationBuilder { } impl DocumentationBuilder { - pub fn new( + #[deprecated(since = "44.0.0", note = "please use `DocumentationBuilder::new_with_details` instead")] + pub fn new() -> Self { + Self::new_with_details(DocSection::default(), "", "") + } + + /// Creates a new [`DocumentationBuilder`] with all required fields + pub fn new_with_details( doc_section: DocSection, description: impl Into, syntax_example: impl Into, From 0d8149b0bd0103b6bf666c539c0239e2fe618d56 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 20 Dec 2024 22:26:12 -0500 Subject: [PATCH 3/4] cmt --- datafusion/doc/src/lib.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/datafusion/doc/src/lib.rs b/datafusion/doc/src/lib.rs index 371dcf1eea17..665e165fa865 100644 --- a/datafusion/doc/src/lib.rs +++ b/datafusion/doc/src/lib.rs @@ -207,7 +207,10 @@ pub struct DocumentationBuilder { } impl DocumentationBuilder { - #[deprecated(since = "44.0.0", note = "please use `DocumentationBuilder::new_with_details` instead")] + #[deprecated( + since = "44.0.0", + note = "please use `DocumentationBuilder::new_with_details` instead" + )] pub fn new() -> Self { Self::new_with_details(DocSection::default(), "", "") } From ccfb150bbfb3147b819ef9c85b0625ad3b6be645 Mon Sep 17 00:00:00 2001 From: Andrew Lamb Date: Fri, 20 Dec 2024 23:20:49 -0500 Subject: [PATCH 4/4] clippy --- datafusion/doc/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/datafusion/doc/src/lib.rs b/datafusion/doc/src/lib.rs index 665e165fa865..6940a8ef3ca2 100644 --- a/datafusion/doc/src/lib.rs +++ b/datafusion/doc/src/lib.rs @@ -207,6 +207,7 @@ pub struct DocumentationBuilder { } impl DocumentationBuilder { + #[allow(clippy::new_without_default)] #[deprecated( since = "44.0.0", note = "please use `DocumentationBuilder::new_with_details` instead"