[DOC] Tweaks for String#scrub (#14892)

1 files changed, 12 insertions, 15 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].