doc-gen: migrate scalar functions (crypto) documentation

Chen-Yuan-Lai · Dec 23, 2024 · c1f1156 · c1f1156
1 parent 405b99c
commit c1f1156
Show file tree

Hide file tree

Showing 8 changed files with 118 additions and 169 deletions.
diff --git a/datafusion-cli/Cargo.lock b/datafusion-cli/Cargo.lock
diff --git a/datafusion/functions-nested/Cargo.toml b/datafusion/functions-nested/Cargo.toml
@@ -46,10 +46,12 @@ arrow-buffer = { workspace = true }
 arrow-ord = { workspace = true }
 arrow-schema = { workspace = true }
 datafusion-common = { workspace = true }
+datafusion-doc = { workspace = true }
 datafusion-execution = { workspace = true }
 datafusion-expr = { workspace = true }
 datafusion-functions = { workspace = true }
 datafusion-functions-aggregate = { workspace = true }
+datafusion-macros = { workspace = true }
 datafusion-physical-expr-common = { workspace = true }
 itertools = { workspace = true, features = ["use_std"] }
 log = { workspace = true }

diff --git a/datafusion/functions/src/crypto/digest.rs b/datafusion/functions/src/crypto/digest.rs
@@ -19,13 +19,40 @@
 use super::basic::{digest, utf8_or_binary_to_binary_type};
 use arrow::datatypes::DataType;
 use datafusion_common::Result;
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
+use datafusion_doc::DocSection;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, TypeSignature::*, Volatility,
 };
+use datafusion_macros::user_doc;
 use std::any::Any;
 use std::sync::OnceLock;
 
+#[user_doc(
+    doc_section(label = "Hashing Functions"),
+    description = "Computes the binary hash of an expression using the specified algorithm.",
+    syntax_example = "digest(expression, algorithm)",
+    sql_example = r#"```sql
+> select digest('foo', 'sha256');
++------------------------------------------+
+| digest(Utf8("foo"), Utf8("sha256"))      |
++------------------------------------------+
+| <binary_hash_result>                     |
++------------------------------------------+
+```"#,
+    standard_argument(name = "expression", prefix = "String"),
+    argument(
+        name = "algorithm",
+        description = "String expression specifying algorithm to use. Must be one of:       
+- md5
+- sha224
+- sha256
+- sha384
+- sha512
+- blake2s
+- blake2b
+- blake3"
+    )
+)]
 #[derive(Debug)]
 pub struct DigestFunc {
     signature: Signature,
@@ -78,43 +105,6 @@ impl ScalarUDFImpl for DigestFunc {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_digest_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_digest_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_HASHING,
-            "Computes the binary hash of an expression using the specified algorithm.",
-            "digest(expression, algorithm)",
-        )
-        .with_sql_example(
-            r#"```sql
-> select digest('foo', 'sha256');
-+------------------------------------------+
-| digest(Utf8("foo"), Utf8("sha256"))      |
-+------------------------------------------+
-| <binary_hash_result>                     |
-+------------------------------------------+
-```"#,
-        )
-        .with_standard_argument("expression", Some("String"))
-        .with_argument(
-            "algorithm",
-            "String expression specifying algorithm to use. Must be one of:
-                
-- md5
-- sha224
-- sha256
-- sha384
-- sha512
-- blake2s
-- blake2b
-- blake3",
-        )
-        .build()
-    })
-}
diff --git a/datafusion/functions/src/crypto/md5.rs b/datafusion/functions/src/crypto/md5.rs
@@ -19,13 +19,28 @@
 use crate::crypto::basic::md5;
 use arrow::datatypes::DataType;
 use datafusion_common::{plan_err, Result};
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
+use datafusion_doc::DocSection;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 use std::any::Any;
 use std::sync::OnceLock;
 
+#[user_doc(
+    doc_section(label = "Hashing Functions"),
+    description = "Computes an MD5 128-bit checksum for a string expression",
+    syntax_example = "md5(expression)",
+    sql_example = r#"```sql
+> select md5('foo');
++-------------------------------------+
+| md5(Utf8("foo"))                    |
++-------------------------------------+
+| <md5_checksum_result>               |
++-------------------------------------+
+```"#,
+    standard_argument(name = "expression", prefix = "String")
+)]
 #[derive(Debug)]
 pub struct Md5Func {
     signature: Signature,
@@ -94,30 +109,6 @@ impl ScalarUDFImpl for Md5Func {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_md5_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_md5_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_HASHING,
-            "Computes an MD5 128-bit checksum for a string expression.",
-            "md5(expression)",
-        )
-        .with_sql_example(
-            r#"```sql
-> select md5('foo');
-+-------------------------------------+
-| md5(Utf8("foo"))                    |
-+-------------------------------------+
-| <md5_checksum_result>               |
-+-------------------------------------+
-```"#,
-        )
-        .with_standard_argument("expression", Some("String"))
-        .build()
-    })
-}
diff --git a/datafusion/functions/src/crypto/sha224.rs b/datafusion/functions/src/crypto/sha224.rs
@@ -19,13 +19,28 @@
 use super::basic::{sha224, utf8_or_binary_to_binary_type};
 use arrow::datatypes::DataType;
 use datafusion_common::Result;
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
+use datafusion_doc::DocSection;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 use std::any::Any;
 use std::sync::OnceLock;
 
+#[user_doc(
+    doc_section(label = "Hashing Functions"),
+    description = "Computes the SHA-224 hash of a binary string.",
+    syntax_example = "sha224(expression",
+    sql_example = r#"```sql
+> select sha224('foo');
++------------------------------------------+
+| sha224(Utf8("foo"))                      |
++------------------------------------------+
+| <sha224_hash_result>                     |
++------------------------------------------+
+```"#,
+    standard_argument(name = "expression", prefix = "String")
+)]
 #[derive(Debug)]
 pub struct SHA224Func {
     signature: Signature,
@@ -50,30 +65,6 @@ impl SHA224Func {
     }
 }
 
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_sha224_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_HASHING,
-            "Computes the SHA-224 hash of a binary string.",
-            "sha224(expression)",
-        )
-        .with_sql_example(
-            r#"```sql
-> select sha224('foo');
-+------------------------------------------+
-| sha224(Utf8("foo"))                      |
-+------------------------------------------+
-| <sha224_hash_result>                     |
-+------------------------------------------+
-```"#,
-        )
-        .with_standard_argument("expression", Some("String"))
-        .build()
-    })
-}
-
 impl ScalarUDFImpl for SHA224Func {
     fn as_any(&self) -> &dyn Any {
         self
@@ -100,6 +91,6 @@ impl ScalarUDFImpl for SHA224Func {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_sha224_doc())
+        self.doc()
     }
 }
diff --git a/datafusion/functions/src/crypto/sha256.rs b/datafusion/functions/src/crypto/sha256.rs
@@ -19,13 +19,28 @@
 use super::basic::{sha256, utf8_or_binary_to_binary_type};
 use arrow::datatypes::DataType;
 use datafusion_common::Result;
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
+use datafusion_doc::DocSection;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 use std::any::Any;
 use std::sync::OnceLock;
 
+#[user_doc(
+    doc_section(label = "Hashing Functions"),
+    description = "Computes the SHA-256 hash of a binary string.",
+    syntax_example = "sha256(expression",
+    sql_example = r#"```sql
+> select sha256('foo');
++--------------------------------------+
+| sha256(Utf8("foo"))                  |
++--------------------------------------+
+| <sha256_hash_result>                 |
++--------------------------------------+
+```"#,
+    standard_argument(name = "expression", prefix = "String")
+)]
 #[derive(Debug)]
 pub struct SHA256Func {
     signature: Signature,
@@ -74,30 +89,6 @@ impl ScalarUDFImpl for SHA256Func {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_sha256_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_sha256_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_HASHING,
-            "Computes the SHA-256 hash of a binary string.",
-            "sha256(expression)",
-        )
-        .with_sql_example(
-            r#"```sql
-> select sha256('foo');
-+--------------------------------------+
-| sha256(Utf8("foo"))                  |
-+--------------------------------------+
-| <sha256_hash_result>                 |
-+--------------------------------------+
-```"#,
-        )
-        .with_standard_argument("expression", Some("String"))
-        .build()
-    })
-}
diff --git a/datafusion/functions/src/crypto/sha384.rs b/datafusion/functions/src/crypto/sha384.rs
@@ -19,13 +19,28 @@
 use super::basic::{sha384, utf8_or_binary_to_binary_type};
 use arrow::datatypes::DataType;
 use datafusion_common::Result;
-use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
+use datafusion_doc::DocSection;
 use datafusion_expr::{
     ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
 };
+use datafusion_macros::user_doc;
 use std::any::Any;
 use std::sync::OnceLock;
 
+#[user_doc(
+    doc_section(label = "Hashing Functions"),
+    description = "Computes the SHA-384 hash of a binary string.",
+    syntax_example = "sha384(expression",
+    sql_example = r#"```sql
+> select sha384('foo');
++--------------------------------------+
+| sha384(Utf8("foo"))                  |
++--------------------------------------+
+| <sha384_hash_result>                 |
++--------------------------------------+
+```"#,
+    standard_argument(name = "expression", prefix = "String")
+)]
 #[derive(Debug)]
 pub struct SHA384Func {
     signature: Signature,
@@ -74,30 +89,6 @@ impl ScalarUDFImpl for SHA384Func {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_sha384_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_sha384_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_HASHING,
-            "Computes the SHA-384 hash of a binary string.",
-            "sha384(expression)",
-        )
-        .with_sql_example(
-            r#"```sql
-> select sha384('foo');
-+-----------------------------------------+
-| sha384(Utf8("foo"))                     |
-+-----------------------------------------+
-| <sha384_hash_result>                    |
-+-----------------------------------------+
-```"#,
-        )
-        .with_standard_argument("expression", Some("String"))
-        .build()
-    })
-}