doc-gen: migrate scalar functions (crypto) documentation (#13918)

* doc-gen: migrate scalar functions (crypto) documentation * doc-gen: fix typo and update function docs --------- Co-authored-by: Cheng-Yuan-Lai <a186235@g,ail.com>
apache · Dec 29, 2024 · fb5378d · fb5378d
1 parent f3e0fa2
commit fb5378d
Show file tree

Hide file tree

Showing 7 changed files with 117 additions and 184 deletions.
diff --git a/datafusion/functions/src/crypto/digest.rs b/datafusion/functions/src/crypto/digest.rs
@@ -19,13 +19,38 @@
 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_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 +103,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,26 @@
 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_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 +107,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,26 @@
 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_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 +63,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 +89,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,26 @@
 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_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 +87,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,26 @@
 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_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 +87,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()
-    })
-}
diff --git a/datafusion/functions/src/crypto/sha512.rs b/datafusion/functions/src/crypto/sha512.rs
@@ -19,13 +19,26 @@
 use super::basic::{sha512, 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_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-512 hash of a binary string.",
+    syntax_example = "sha512(expression)",
+    sql_example = r#"```sql
+> select sha512('foo');
++-------------------------------------------+
+| sha512(Utf8("foo"))                       |
++-------------------------------------------+
+| <sha512_hash_result>                      |
++-------------------------------------------+
+```"#,
+    standard_argument(name = "expression", prefix = "String")
+)]
 #[derive(Debug)]
 pub struct SHA512Func {
     signature: Signature,
@@ -74,30 +87,6 @@ impl ScalarUDFImpl for SHA512Func {
     }
 
     fn documentation(&self) -> Option<&Documentation> {
-        Some(get_sha512_doc())
+        self.doc()
     }
 }
-
-static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
-
-fn get_sha512_doc() -> &'static Documentation {
-    DOCUMENTATION.get_or_init(|| {
-        Documentation::builder(
-            DOC_SECTION_HASHING,
-            "Computes the SHA-512 hash of a binary string.",
-            "sha512(expression)",
-        )
-        .with_sql_example(
-            r#"```sql
-> select sha512('foo');
-+-------------------------------------------+
-| sha512(Utf8("foo"))                       |
-+-------------------------------------------+
-| <sha512_hash_result>                      |
-+-------------------------------------------+
-```"#,
-        )
-        .with_argument("expression", "String")
-        .build()
-    })
-}