From cb52809ca124cb627293a666e8cbb44e031eeec1 Mon Sep 17 00:00:00 2001
From: Burdette Lamar <BurdetteLamar@Yahoo.com>
Date: Tue, 21 Oct 2025 15:48:11 -0500
Subject: [DOC] Tweaks for String#scrub (#14892)

---
 doc/string/scrub.rdoc | 27 ++++++++++++---------------
 string.c              |  4 ++--
 2 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/doc/string/scrub.rdoc b/doc/string/scrub.rdoc
index 1a5b1c79d0..5ace376cdb 100644
--- a/doc/string/scrub.rdoc
+++ b/doc/string/scrub.rdoc
@@ -1,25 +1,22 @@
 Returns a copy of +self+ with each invalid byte sequence replaced
 by the given +replacement_string+.
 
-With no block given and no argument, replaces each invalid sequence
-with the default replacement string
-(<tt>"�"</tt> for a Unicode encoding, <tt>'?'</tt> otherwise):
+With no block given, replaces each invalid sequence
+with the given +default_replacement_string+
+(by default, <tt>"�"</tt> for a Unicode encoding, <tt>'?'</tt> otherwise):
 
-  s = "foo\x81\x81bar"
-  s.scrub # => "foo��bar"
+  "foo\x81\x81bar"scrub                             # => "foo��bar"
+  "foo\x81\x81bar".force_encoding('US-ASCII').scrub # => "foo??bar"
+  "foo\x81\x81bar".scrub('xyzzy')                   # => "fooxyzzyxyzzybar"
 
-With no block given and argument +replacement_string+ given,
-replaces each invalid sequence with that string:
+With a block given, calls the block with each invalid sequence,
+and replaces that sequence with the return value of the block:
 
-  "foo\x81\x81bar".scrub('xyzzy') # => "fooxyzzyxyzzybar"
+  "foo\x81\x81bar".scrub {|sequence| p sequence; 'XYZZY' } # => "fooXYZZYXYZZYbar"
 
-With a block given, replaces each invalid sequence with the value
-of the block:
-
-  "foo\x81\x81bar".scrub {|bytes| p bytes; 'XYZZY' }
-  # => "fooXYZZYXYZZYbar"
-
-Output:
+Output :
 
   "\x81"
   "\x81"
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index 344b38d255..8f9d19fb54 100644
--- a/string.c
+++ b/string.c
@@ -11911,8 +11911,8 @@ enc_str_scrub(rb_encoding *enc, VALUE str, VALUE repl, int cr)
 
 /*
  *  call-seq:
- *    scrub(replacement_string = default_replacement) -> new_string
- *    scrub{|bytes| ... } -> new_string
+ *    scrub(replacement_string = default_replacement_string) -> new_string
+ *    scrub{|sequence| ... } -> new_string
  *
  *  :include: doc/string/scrub.rdoc
  *
-- 
cgit v1.2.3