From 59e0489248036f5923e04fdf16ce3d8244ed038d Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Thu, 20 Nov 2025 16:03:58 -0600
Subject: [PATCH] [DOC] Tweaks for String#upcase (#15244)

---
 doc/string/upcase.rdoc | 20 ++++++++++++++++++++
 string.c               | 11 +----------
 2 files changed, 21 insertions(+), 10 deletions(-)
 create mode 100644 doc/string/upcase.rdoc

diff --git a/doc/string/upcase.rdoc b/doc/string/upcase.rdoc
new file mode 100644
index 0000000000..5a9cce217f
--- /dev/null
+++ b/doc/string/upcase.rdoc
@@ -0,0 +1,20 @@
+Returns a new string containing the upcased characters in +self+:
+
+   'Hello, World!'.upcase     # => "HELLO, WORLD!"
+
+The sizes of +self+ and the upcased result may differ:
+
+   s = 'Straße'
+   s.size        # => 6
+   s.upcase      # => "STRASSE"
+   s.upcase.size # => 7
+
+Some characters (and some character sets) do not have upcased and downcased versions:
+
+   s = 'よろしくお願いします'
+   s.upcase == s # => true
+
+The casing may be affected by the given +mapping+;
+see {Case Mapping}[rdoc-ref:case_mapping.rdoc].
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index d78d7320be..c4ac00c342 100644
--- a/string.c
+++ b/string.c
@@ -8001,16 +8001,7 @@ rb_str_upcase_bang(int argc, VALUE *argv, VALUE str)
  *  call-seq:
  *    upcase(mapping) -> string
  *
- *  Returns a string containing the upcased characters in +self+:
- *
- *     s = 'Hello World!' # => "Hello World!"
- *     s.upcase           # => "HELLO WORLD!"
- *
- *  The casing may be affected by the given +mapping+;
- *  see {Case Mapping}[rdoc-ref:case_mapping.rdoc].
- *
- *  Related: String#upcase!, String#downcase, String#downcase!.
- *
+ *  :include: doc/string/upcase.rdoc
  */
 
 static VALUE