This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/datafusion.git
The following commit(s) were added to refs/heads/main by this push:
new 8fd792f312 Restore `DocBuilder::new()` to avoid breaking API change
(#13870)
8fd792f312 is described below
commit 8fd792f312b0c94e097219a97183d1ab336345d0
Author: Andrew Lamb <[email protected]>
AuthorDate: Sun Dec 22 16:38:38 2024 -0500
Restore `DocBuilder::new()` to avoid breaking API change (#13870)
* Fix build
* Restore DocBuilder::new(), deprecate
* cmt
* clippy
---
datafusion/doc/src/lib.rs | 38 +++++++++++++++++++++++++++++++++-----
1 file changed, 33 insertions(+), 5 deletions(-)
diff --git a/datafusion/doc/src/lib.rs b/datafusion/doc/src/lib.rs
index 3d8fae6cd3..6940a8ef3c 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<String>,
syntax_example: impl Into<String>,
) -> 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,17 @@ pub struct DocumentationBuilder {
}
impl DocumentationBuilder {
- pub fn new(
+ #[allow(clippy::new_without_default)]
+ #[deprecated(
+ since = "44.0.0",
+ note = "please use `DocumentationBuilder::new_with_details` instead"
+ )]
+ pub fn new() -> Self {
+ Self::new_with_details(DocSection::default(), "<no description>", "<no
example>")
+ }
+
+ /// Creates a new [`DocumentationBuilder`] with all required fields
+ pub fn new_with_details(
doc_section: DocSection,
description: impl Into<String>,
syntax_example: impl Into<String>,
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
