doc-gen: migrate window functions documentation to attribute based (#…

…13739) * doc-gen: migrate window functions documentation Signed-off-by: zjregee <[email protected]> * fix: update Cargo.lock --------- Signed-off-by: zjregee <[email protected]>
apache · Dec 13, 2024 · 6ac1999 · 6ac1999
1 parent 4148729
commit 6ac1999
Show file tree

Hide file tree

Showing 5 changed files with 44 additions and 54 deletions.
diff --git a/datafusion-cli/Cargo.lock b/datafusion-cli/Cargo.lock
diff --git a/datafusion/functions-window/Cargo.toml b/datafusion/functions-window/Cargo.toml
@@ -39,8 +39,10 @@ path = "src/lib.rs"
 
 [dependencies]
 datafusion-common = { workspace = true }
+datafusion-doc = { workspace = true }
 datafusion-expr = { workspace = true }
 datafusion-functions-window-common = { workspace = true }
+datafusion-macros = { workspace = true }
 datafusion-physical-expr = { workspace = true }
 datafusion-physical-expr-common = { workspace = true }
 log = { workspace = true }

diff --git a/datafusion/functions-window/src/cume_dist.rs b/datafusion/functions-window/src/cume_dist.rs
@@ -21,18 +21,18 @@ use datafusion_common::arrow::array::{ArrayRef, Float64Array};
 use datafusion_common::arrow::datatypes::DataType;
 use datafusion_common::arrow::datatypes::Field;
 use datafusion_common::Result;
-use datafusion_expr::window_doc_sections::DOC_SECTION_RANKING;
 use datafusion_expr::{
     Documentation, PartitionEvaluator, Signature, Volatility, WindowUDFImpl,
 };
 use datafusion_functions_window_common::field;
 use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
+use datafusion_macros::user_doc;
 use field::WindowUDFFieldArgs;
 use std::any::Any;
 use std::fmt::Debug;
 use std::iter;
 use std::ops::Range;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 define_udwf_and_expr!(
     CumeDist,
@@ -41,6 +41,11 @@ define_udwf_and_expr!(
 );
 
 /// CumeDist calculates the cume_dist in the window function with order by
+#[user_doc(
+    doc_section(label = "Ranking Functions"),
+    description = "Relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).",
+    syntax_example = "cume_dist()"
+)]
 #[derive(Debug)]
 pub struct CumeDist {
     signature: Signature,
@@ -86,19 +91,10 @@ impl WindowUDFImpl for CumeDist {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_cume_dist_doc())
+        self.doc()
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_cume_dist_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(DOC_SECTION_RANKING, "Relative rank of the current row: (number of rows preceding or peer with current row) / (total rows).", "cume_dist()")
-            .build()
-    })
-}
-
 #[derive(Debug, Default)]
 pub(crate) struct CumeDistEvaluator;
 

diff --git a/datafusion/functions-window/src/ntile.rs b/datafusion/functions-window/src/ntile.rs
@@ -19,20 +19,20 @@
 
 use std::any::Any;
 use std::fmt::Debug;
-use std::sync::{Arc, OnceLock};
+use std::sync::Arc;
 
 use crate::utils::{
     get_scalar_value_from_args, get_signed_integer, get_unsigned_integer,
 };
 use datafusion_common::arrow::array::{ArrayRef, UInt64Array};
 use datafusion_common::arrow::datatypes::{DataType, Field};
 use datafusion_common::{exec_err, DataFusionError, Result};
-use datafusion_expr::window_doc_sections::DOC_SECTION_RANKING;
 use datafusion_expr::{
     Documentation, Expr, PartitionEvaluator, Signature, Volatility, WindowUDFImpl,
 };
 use datafusion_functions_window_common::field;
 use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
+use datafusion_macros::user_doc;
 use field::WindowUDFFieldArgs;
 
 get_or_init_udwf!(
@@ -45,6 +45,15 @@ pub fn ntile(arg: Expr) -> Expr {
     ntile_udwf().call(vec![arg])
 }
 
+#[user_doc(
+    doc_section(label = "Ranking Functions"),
+    description = "Integer ranging from 1 to the argument value, dividing the partition as equally as possible",
+    syntax_example = "ntile(expression)",
+    argument(
+        name = "expression",
+        description = "An integer describing the number groups the partition should be split into"
+    )
+)]
 #[derive(Debug)]
 pub struct Ntile {
     signature: Signature,
@@ -78,16 +87,6 @@ impl Default for Ntile {
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_ntile_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(DOC_SECTION_RANKING, "Integer ranging from 1 to the argument value, dividing the partition as equally as possible", "ntile(expression)")
-            .with_argument("expression","An integer describing the number groups the partition should be split into")
-            .build()
-    })
-}
-
 impl WindowUDFImpl for Ntile {
     fn as_any(&self) -> &dyn Any {
         self
@@ -135,7 +134,7 @@ impl WindowUDFImpl for Ntile {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_ntile_doc())
+        self.doc()
     }
 }
 

diff --git a/datafusion/functions-window/src/row_number.rs b/datafusion/functions-window/src/row_number.rs
@@ -23,17 +23,16 @@ use datafusion_common::arrow::compute::SortOptions;
 use datafusion_common::arrow::datatypes::DataType;
 use datafusion_common::arrow::datatypes::Field;
 use datafusion_common::{Result, ScalarValue};
-use datafusion_expr::window_doc_sections::DOC_SECTION_RANKING;
 use datafusion_expr::{
     Documentation, PartitionEvaluator, Signature, Volatility, WindowUDFImpl,
 };
 use datafusion_functions_window_common::field;
 use datafusion_functions_window_common::partition::PartitionEvaluatorArgs;
+use datafusion_macros::user_doc;
 use field::WindowUDFFieldArgs;
 use std::any::Any;
 use std::fmt::Debug;
 use std::ops::Range;
-use std::sync::OnceLock;
 
 define_udwf_and_expr!(
     RowNumber,
@@ -42,6 +41,11 @@ define_udwf_and_expr!(
 );
 
 /// row_number expression
+#[user_doc(
+    doc_section(label = "Ranking Functions"),
+    description = "Number of the current row within its partition, counting from 1.",
+    syntax_example = "row_number()"
+)]
 #[derive(Debug)]
 pub struct RowNumber {
     signature: Signature,
@@ -62,19 +66,6 @@ impl Default for RowNumber {
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_row_number_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_RANKING,
-            "Number of the current row within its partition, counting from 1.",
-            "row_number()",
-        )
-        .build()
-    })
-}
-
 impl WindowUDFImpl for RowNumber {
     fn as_any(&self) -> &dyn Any {
         self
@@ -107,7 +98,7 @@ impl WindowUDFImpl for RowNumber {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_row_number_doc())
+        self.doc()
     }
 }