From b69fa6723dba4f13c14c292bf9a92e309ca9d22c Mon Sep 17 00:00:00 2001
From: Andrew Lamb <andrew@nerdnetworks.org>
Date: Thu, 12 Dec 2024 19:38:55 -0500
Subject: [PATCH] Minor: Add documentation explaining that initcap oly works
 for ASCII (#13749)

---
 datafusion/functions/src/string/initcap.rs    | 29 +++++++++++++------
 .../source/user-guide/sql/scalar_functions.md |  4 ++-
 2 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/datafusion/functions/src/string/initcap.rs b/datafusion/functions/src/string/initcap.rs
index 4ca0d6b6499a..2780dcaeeb83 100644
--- a/datafusion/functions/src/string/initcap.rs
+++ b/datafusion/functions/src/string/initcap.rs
@@ -90,25 +90,36 @@ fn get_initcap_doc() -> &'static Documentation {
     DOCUMENTATION.get_or_init(|| {
         Documentation::builder(
             DOC_SECTION_STRING,
-            "Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters.",
-            "initcap(str)")
-            .with_sql_example(r#"```sql
+            "Capitalizes the first character in each word in the ASCII input string. \
+            Words are delimited by non-alphanumeric characters.\n\n\
+            Note this function does not support UTF-8 characters.",
+            "initcap(str)",
+        )
+        .with_sql_example(
+            r#"```sql
 > select initcap('apache datafusion');
 +------------------------------------+
 | initcap(Utf8("apache datafusion")) |
 +------------------------------------+
 | Apache Datafusion                  |
 +------------------------------------+
-```"#)
-            .with_standard_argument("str", Some("String"))
-            .with_related_udf("lower")
-            .with_related_udf("upper")
-            .build()
+```"#,
+        )
+        .with_standard_argument("str", Some("String"))
+        .with_related_udf("lower")
+        .with_related_udf("upper")
+        .build()
     })
 }
 
-/// Converts the first letter of each word to upper case and the rest to lower case. Words are sequences of alphanumeric characters separated by non-alphanumeric characters.
+/// Converts the first letter of each word to upper case and the rest to lower
+/// case. Words are sequences of alphanumeric characters separated by
+/// non-alphanumeric characters.
+///
+/// Example:
+/// ```sql
 /// initcap('hi THOMAS') = 'Hi Thomas'
+/// ```
 fn initcap<T: OffsetSizeTrait>(args: &[ArrayRef]) -> Result<ArrayRef> {
     let string_array = as_generic_string_array::<T>(&args[0])?;
 
diff --git a/docs/source/user-guide/sql/scalar_functions.md b/docs/source/user-guide/sql/scalar_functions.md
index 208d18f0e5ab..4e74cfc54ae5 100644
--- a/docs/source/user-guide/sql/scalar_functions.md
+++ b/docs/source/user-guide/sql/scalar_functions.md
@@ -1046,7 +1046,9 @@ find_in_set(str, strlist)
 
 ### `initcap`
 
-Capitalizes the first character in each word in the input string. Words are delimited by non-alphanumeric characters.
+Capitalizes the first character in each word in the ASCII input string. Words are delimited by non-alphanumeric characters.
+
+Note this function does not support UTF-8 characters.
 
 ```
 initcap(str)