Skip to content

Commit fb5378d

Browse files
Chen-Yuan-LaiCheng-Yuan-Lai
Chen-Yuan-Lai
and
Cheng-Yuan-Lai
authored
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>
1 parent f3e0fa2 commit fb5378d

File tree

7 files changed

+117
-184
lines changed

7 files changed

+117
-184
lines changed

‎datafusion/functions/src/crypto/digest.rs‎

Lines changed: 28 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,38 @@
1919
use super::basic::{digest, utf8_or_binary_to_binary_type};
2020
use arrow::datatypes::DataType;
2121
use datafusion_common::Result;
22-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
2322
use datafusion_expr::{
2423
ColumnarValue, Documentation, ScalarUDFImpl, Signature, TypeSignature::*, Volatility,
2524
};
25+
use datafusion_macros::user_doc;
2626
use std::any::Any;
27-
use std::sync::OnceLock;
2827

28+
#[user_doc(
29+
doc_section(label = "Hashing Functions"),
30+
description = "Computes the binary hash of an expression using the specified algorithm.",
31+
syntax_example = "digest(expression, algorithm)",
32+
sql_example = r#"```sql
33+
> select digest('foo', 'sha256');
34+
+------------------------------------------+
35+
| digest(Utf8("foo"), Utf8("sha256")) |
36+
+------------------------------------------+
37+
| <binary_hash_result> |
38+
+------------------------------------------+
39+
```"#,
40+
standard_argument(name = "expression", prefix = "String"),
41+
argument(
42+
name = "algorithm",
43+
description = "String expression specifying algorithm to use. Must be one of:
44+
- md5
45+
- sha224
46+
- sha256
47+
- sha384
48+
- sha512
49+
- blake2s
50+
- blake2b
51+
- blake3"
52+
)
53+
)]
2954
#[derive(Debug)]
3055
pub struct DigestFunc {
3156
signature: Signature,
@@ -78,43 +103,6 @@ impl ScalarUDFImpl for DigestFunc {
78103
}
79104

80105
fn documentation(&self) -> Option<&Documentation> {
81-
Some(get_digest_doc())
106+
self.doc()
82107
}
83108
}
84-
85-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
86-
87-
fn get_digest_doc() -> &'static Documentation {
88-
DOCUMENTATION.get_or_init(|| {
89-
Documentation::builder(
90-
DOC_SECTION_HASHING,
91-
"Computes the binary hash of an expression using the specified algorithm.",
92-
"digest(expression, algorithm)",
93-
)
94-
.with_sql_example(
95-
r#"```sql
96-
> select digest('foo', 'sha256');
97-
+------------------------------------------+
98-
| digest(Utf8("foo"), Utf8("sha256")) |
99-
+------------------------------------------+
100-
| <binary_hash_result> |
101-
+------------------------------------------+
102-
```"#,
103-
)
104-
.with_standard_argument("expression", Some("String"))
105-
.with_argument(
106-
"algorithm",
107-
"String expression specifying algorithm to use. Must be one of:
108-
109-
- md5
110-
- sha224
111-
- sha256
112-
- sha384
113-
- sha512
114-
- blake2s
115-
- blake2b
116-
- blake3",
117-
)
118-
.build()
119-
})
120-
}

‎datafusion/functions/src/crypto/md5.rs‎

Lines changed: 16 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,26 @@
1919
use crate::crypto::basic::md5;
2020
use arrow::datatypes::DataType;
2121
use datafusion_common::{plan_err, Result};
22-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
2322
use datafusion_expr::{
2423
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
2524
};
25+
use datafusion_macros::user_doc;
2626
use std::any::Any;
27-
use std::sync::OnceLock;
2827

28+
#[user_doc(
29+
doc_section(label = "Hashing Functions"),
30+
description = "Computes an MD5 128-bit checksum for a string expression.",
31+
syntax_example = "md5(expression)",
32+
sql_example = r#"```sql
33+
> select md5('foo');
34+
+-------------------------------------+
35+
| md5(Utf8("foo")) |
36+
+-------------------------------------+
37+
| <md5_checksum_result> |
38+
+-------------------------------------+
39+
```"#,
40+
standard_argument(name = "expression", prefix = "String")
41+
)]
2942
#[derive(Debug)]
3043
pub struct Md5Func {
3144
signature: Signature,
@@ -94,30 +107,6 @@ impl ScalarUDFImpl for Md5Func {
94107
}
95108

96109
fn documentation(&self) -> Option<&Documentation> {
97-
Some(get_md5_doc())
110+
self.doc()
98111
}
99112
}
100-
101-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
102-
103-
fn get_md5_doc() -> &'static Documentation {
104-
DOCUMENTATION.get_or_init(|| {
105-
Documentation::builder(
106-
DOC_SECTION_HASHING,
107-
"Computes an MD5 128-bit checksum for a string expression.",
108-
"md5(expression)",
109-
)
110-
.with_sql_example(
111-
r#"```sql
112-
> select md5('foo');
113-
+-------------------------------------+
114-
| md5(Utf8("foo")) |
115-
+-------------------------------------+
116-
| <md5_checksum_result> |
117-
+-------------------------------------+
118-
```"#,
119-
)
120-
.with_standard_argument("expression", Some("String"))
121-
.build()
122-
})
123-
}

‎datafusion/functions/src/crypto/sha224.rs‎

Lines changed: 16 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,26 @@
1919
use super::basic::{sha224, utf8_or_binary_to_binary_type};
2020
use arrow::datatypes::DataType;
2121
use datafusion_common::Result;
22-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
2322
use datafusion_expr::{
2423
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
2524
};
25+
use datafusion_macros::user_doc;
2626
use std::any::Any;
27-
use std::sync::OnceLock;
2827

28+
#[user_doc(
29+
doc_section(label = "Hashing Functions"),
30+
description = "Computes the SHA-224 hash of a binary string.",
31+
syntax_example = "sha224(expression)",
32+
sql_example = r#"```sql
33+
> select sha224('foo');
34+
+------------------------------------------+
35+
| sha224(Utf8("foo")) |
36+
+------------------------------------------+
37+
| <sha224_hash_result> |
38+
+------------------------------------------+
39+
```"#,
40+
standard_argument(name = "expression", prefix = "String")
41+
)]
2942
#[derive(Debug)]
3043
pub struct SHA224Func {
3144
signature: Signature,
@@ -50,30 +63,6 @@ impl SHA224Func {
5063
}
5164
}
5265

53-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
54-
55-
fn get_sha224_doc() -> &'static Documentation {
56-
DOCUMENTATION.get_or_init(|| {
57-
Documentation::builder(
58-
DOC_SECTION_HASHING,
59-
"Computes the SHA-224 hash of a binary string.",
60-
"sha224(expression)",
61-
)
62-
.with_sql_example(
63-
r#"```sql
64-
> select sha224('foo');
65-
+------------------------------------------+
66-
| sha224(Utf8("foo")) |
67-
+------------------------------------------+
68-
| <sha224_hash_result> |
69-
+------------------------------------------+
70-
```"#,
71-
)
72-
.with_standard_argument("expression", Some("String"))
73-
.build()
74-
})
75-
}
76-
7766
impl ScalarUDFImpl for SHA224Func {
7867
fn as_any(&self) -> &dyn Any {
7968
self
@@ -100,6 +89,6 @@ impl ScalarUDFImpl for SHA224Func {
10089
}
10190

10291
fn documentation(&self) -> Option<&Documentation> {
103-
Some(get_sha224_doc())
92+
self.doc()
10493
}
10594
}

‎datafusion/functions/src/crypto/sha256.rs‎

Lines changed: 16 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,26 @@
1919
use super::basic::{sha256, utf8_or_binary_to_binary_type};
2020
use arrow::datatypes::DataType;
2121
use datafusion_common::Result;
22-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
2322
use datafusion_expr::{
2423
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
2524
};
25+
use datafusion_macros::user_doc;
2626
use std::any::Any;
27-
use std::sync::OnceLock;
2827

28+
#[user_doc(
29+
doc_section(label = "Hashing Functions"),
30+
description = "Computes the SHA-256 hash of a binary string.",
31+
syntax_example = "sha256(expression)",
32+
sql_example = r#"```sql
33+
> select sha256('foo');
34+
+--------------------------------------+
35+
| sha256(Utf8("foo")) |
36+
+--------------------------------------+
37+
| <sha256_hash_result> |
38+
+--------------------------------------+
39+
```"#,
40+
standard_argument(name = "expression", prefix = "String")
41+
)]
2942
#[derive(Debug)]
3043
pub struct SHA256Func {
3144
signature: Signature,
@@ -74,30 +87,6 @@ impl ScalarUDFImpl for SHA256Func {
7487
}
7588

7689
fn documentation(&self) -> Option<&Documentation> {
77-
Some(get_sha256_doc())
90+
self.doc()
7891
}
7992
}
80-
81-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
82-
83-
fn get_sha256_doc() -> &'static Documentation {
84-
DOCUMENTATION.get_or_init(|| {
85-
Documentation::builder(
86-
DOC_SECTION_HASHING,
87-
"Computes the SHA-256 hash of a binary string.",
88-
"sha256(expression)",
89-
)
90-
.with_sql_example(
91-
r#"```sql
92-
> select sha256('foo');
93-
+--------------------------------------+
94-
| sha256(Utf8("foo")) |
95-
+--------------------------------------+
96-
| <sha256_hash_result> |
97-
+--------------------------------------+
98-
```"#,
99-
)
100-
.with_standard_argument("expression", Some("String"))
101-
.build()
102-
})
103-
}

‎datafusion/functions/src/crypto/sha384.rs‎

Lines changed: 16 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,26 @@
1919
use super::basic::{sha384, utf8_or_binary_to_binary_type};
2020
use arrow::datatypes::DataType;
2121
use datafusion_common::Result;
22-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
2322
use datafusion_expr::{
2423
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
2524
};
25+
use datafusion_macros::user_doc;
2626
use std::any::Any;
27-
use std::sync::OnceLock;
2827

28+
#[user_doc(
29+
doc_section(label = "Hashing Functions"),
30+
description = "Computes the SHA-384 hash of a binary string.",
31+
syntax_example = "sha384(expression)",
32+
sql_example = r#"```sql
33+
> select sha384('foo');
34+
+-----------------------------------------+
35+
| sha384(Utf8("foo")) |
36+
+-----------------------------------------+
37+
| <sha384_hash_result> |
38+
+-----------------------------------------+
39+
```"#,
40+
standard_argument(name = "expression", prefix = "String")
41+
)]
2942
#[derive(Debug)]
3043
pub struct SHA384Func {
3144
signature: Signature,
@@ -74,30 +87,6 @@ impl ScalarUDFImpl for SHA384Func {
7487
}
7588

7689
fn documentation(&self) -> Option<&Documentation> {
77-
Some(get_sha384_doc())
90+
self.doc()
7891
}
7992
}
80-
81-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
82-
83-
fn get_sha384_doc() -> &'static Documentation {
84-
DOCUMENTATION.get_or_init(|| {
85-
Documentation::builder(
86-
DOC_SECTION_HASHING,
87-
"Computes the SHA-384 hash of a binary string.",
88-
"sha384(expression)",
89-
)
90-
.with_sql_example(
91-
r#"```sql
92-
> select sha384('foo');
93-
+-----------------------------------------+
94-
| sha384(Utf8("foo")) |
95-
+-----------------------------------------+
96-
| <sha384_hash_result> |
97-
+-----------------------------------------+
98-
```"#,
99-
)
100-
.with_standard_argument("expression", Some("String"))
101-
.build()
102-
})
103-
}

‎datafusion/functions/src/crypto/sha512.rs‎

Lines changed: 16 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,26 @@
1919
use super::basic::{sha512, utf8_or_binary_to_binary_type};
2020
use arrow::datatypes::DataType;
2121
use datafusion_common::Result;
22-
use datafusion_expr::scalar_doc_sections::DOC_SECTION_HASHING;
2322
use datafusion_expr::{
2423
ColumnarValue, Documentation, ScalarUDFImpl, Signature, Volatility,
2524
};
25+
use datafusion_macros::user_doc;
2626
use std::any::Any;
27-
use std::sync::OnceLock;
2827

28+
#[user_doc(
29+
doc_section(label = "Hashing Functions"),
30+
description = "Computes the SHA-512 hash of a binary string.",
31+
syntax_example = "sha512(expression)",
32+
sql_example = r#"```sql
33+
> select sha512('foo');
34+
+-------------------------------------------+
35+
| sha512(Utf8("foo")) |
36+
+-------------------------------------------+
37+
| <sha512_hash_result> |
38+
+-------------------------------------------+
39+
```"#,
40+
standard_argument(name = "expression", prefix = "String")
41+
)]
2942
#[derive(Debug)]
3043
pub struct SHA512Func {
3144
signature: Signature,
@@ -74,30 +87,6 @@ impl ScalarUDFImpl for SHA512Func {
7487
}
7588

7689
fn documentation(&self) -> Option<&Documentation> {
77-
Some(get_sha512_doc())
90+
self.doc()
7891
}
7992
}
80-
81-
static DOCUMENTATION: OnceLock<Documentation> = OnceLock::new();
82-
83-
fn get_sha512_doc() -> &'static Documentation {
84-
DOCUMENTATION.get_or_init(|| {
85-
Documentation::builder(
86-
DOC_SECTION_HASHING,
87-
"Computes the SHA-512 hash of a binary string.",
88-
"sha512(expression)",
89-
)
90-
.with_sql_example(
91-
r#"```sql
92-
> select sha512('foo');
93-
+-------------------------------------------+
94-
| sha512(Utf8("foo")) |
95-
+-------------------------------------------+
96-
| <sha512_hash_result> |
97-
+-------------------------------------------+
98-
```"#,
99-
)
100-
.with_argument("expression", "String")
101-
.build()
102-
})
103-
}

0 commit comments

Comments
 (0)