[DOC] Tweaks for String#succ

2 files changed, 54 insertions, 51 deletions

diff --git a/doc/string/succ.rdoc b/doc/string/succ.rdoc
new file mode 100644
index 0000000000..3653112b83
--- /dev/null
+++ b/doc/string/succ.rdoc
@@ -0,0 +1,53 @@
+Returns the successor to +self+. The successor is calculated by
+incrementing characters.
+
+The first character to be incremented is the rightmost alphanumeric:
+or, if no alphanumerics, the rightmost character:
+
+  'THX1138'.succ   # => "THX1139"
+  '<<koala>>'.succ # => "<<koalb>>"
+  '***'.succ       # => '**+'
+  'тест'.succ      # => "тесу"
+  'こんにちは'.succ  # => "こんにちば"
+
+The successor to a digit is another digit, "carrying" to the next-left
+character for a "rollover" from 9 to 0, and prepending another digit
+if necessary:
+
+  '00'.succ # => "01"
+  '09'.succ # => "10"
+  '99'.succ # => "100"
+
+The successor to a letter is another letter of the same case,
+carrying to the next-left character for a rollover,
+and prepending another same-case letter if necessary:
+
+  'aa'.succ # => "ab"
+  'az'.succ # => "ba"
+  'zz'.succ # => "aaa"
+  'AA'.succ # => "AB"
+  'AZ'.succ # => "BA"
+  'ZZ'.succ # => "AAA"
+
+The successor to a non-alphanumeric character is the next character
+in the underlying character set's collating sequence,
+carrying to the next-left character for a rollover,
+and prepending another character if necessary:
+
+  s = 0.chr * 3   # => "\x00\x00\x00"
+  s.succ        # => "\x00\x00\x01"
+  s = 255.chr * 3 # => "\xFF\xFF\xFF"
+  s.succ        # => "\x01\x00\x00\x00"
+
+Carrying can occur between and among mixtures of alphanumeric characters:
+
+  s = 'zz99zz99' # => "zz99zz99"
+  s.succ         # => "aaa00aa00"
+  s = '99zz99zz' # => "99zz99zz"
+  s.succ         # => "100aa00aa"
+
+The successor to an empty +String+ is a new empty +String+:
+
+  ''.succ # => ""
+
+Related: see {Converting to New String}[rdoc-ref:String@Converting+to+New+String].
diff --git a/string.c b/string.c
index 89445df244..58fb70a8e5 100644
--- a/string.c
+++ b/string.c
@@ -5315,57 +5315,7 @@ static VALUE str_succ(VALUE str);
  *  call-seq:
  *    succ -> new_str
  *
- *  Returns the successor to +self+. The successor is calculated by
- *  incrementing characters.
- *
- *  The first character to be incremented is the rightmost alphanumeric:
- *  or, if no alphanumerics, the rightmost character:
- *
- *    'THX1138'.succ # => "THX1139"
- *    '<<koala>>'.succ # => "<<koalb>>"
- *    '***'.succ # => '**+'
- *
- *  The successor to a digit is another digit, "carrying" to the next-left
- *  character for a "rollover" from 9 to 0, and prepending another digit
- *  if necessary:
- *
- *    '00'.succ # => "01"
- *    '09'.succ # => "10"
- *    '99'.succ # => "100"
- *
- *  The successor to a letter is another letter of the same case,
- *  carrying to the next-left character for a rollover,
- *  and prepending another same-case letter if necessary:
- *
- *    'aa'.succ # => "ab"
- *    'az'.succ # => "ba"
- *    'zz'.succ # => "aaa"
- *    'AA'.succ # => "AB"
- *    'AZ'.succ # => "BA"
- *    'ZZ'.succ # => "AAA"
- *
- *  The successor to a non-alphanumeric character is the next character
- *  in the underlying character set's collating sequence,
- *  carrying to the next-left character for a rollover,
- *  and prepending another character if necessary:
- *
- *    s = 0.chr * 3
- *    s # => "\x00\x00\x00"
- *    s.succ # => "\x00\x00\x01"
- *    s = 255.chr * 3
- *    s # => "\xFF\xFF\xFF"
- *    s.succ # => "\x01\x00\x00\x00"
- *
- *  Carrying can occur between and among mixtures of alphanumeric characters:
- *
- *    s = 'zz99zz99'
- *    s.succ # => "aaa00aa00"
- *    s = '99zz99zz'
- *    s.succ # => "100aa00aa"
- *
- *  The successor to an empty +String+ is a new empty +String+:
- *
- *    ''.succ # => ""
+ *  :include: doc/string/succ.rdoc
  *
  */