From fcb030929f7485262cdf58b730f5a729cec96d92 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Fri, 25 Sep 2020 13:53:44 -0500
Subject: [PATCH 1/2] Enhanced RDoc for String#succ

---
 string.c | 74 ++++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 53 insertions(+), 21 deletions(-)

diff --git a/string.c b/string.c
index e2c7bfbe05b80e..b23dddb7b7141a 100644
--- a/string.c
+++ b/string.c
@@ -4160,27 +4160,59 @@ static VALUE str_succ(VALUE str);
 
 /*
  *  call-seq:
- *     str.succ   -> new_str
- *     str.next   -> new_str
- *
- *  Returns the successor to <i>str</i>. The successor is calculated by
- *  incrementing characters starting from the rightmost alphanumeric (or
- *  the rightmost character if there are no alphanumerics) in the
- *  string. Incrementing a digit always results in another digit, and
- *  incrementing a letter results in another letter of the same case.
- *  Incrementing nonalphanumerics uses the underlying character set's
- *  collating sequence.
- *
- *  If the increment generates a ``carry,'' the character to the left of
- *  it is incremented. This process repeats until there is no carry,
- *  adding an additional character if necessary.
- *
- *     "abcd".succ        #=> "abce"
- *     "THX1138".succ     #=> "THX1139"
- *     "<<koala>>".succ   #=> "<<koalb>>"
- *     "1999zzz".succ     #=> "2000aaa"
- *     "ZZZ9999".succ     #=> "AAAA0000"
- *     "***".succ         #=> "**+"
+ *    string.succ -> new_str
+ *    string.next -> 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 all types of characters:
+ *    s = format("%s%s%s%s%s", 255.chr, '9', 'z', '9', 255.chr)
+ *    s # => "\xFF9z9\xFF"
+ *    s.succ # => "\xFF10a0\xFF"
+ *    s = format("%s%s%s%s%s", 'z', 255.chr, '9', 255.chr, 'z')
+ *    s # => "z\xFF9\xFFz"
+ *    s.succ # => "z\xFF9\xFFaa"
+ *    s = format("%s%s%s%s%s", '9', 'z', 255.chr, 'z', '9')
+ *    s # => "9z\xFFz9"
+ *    s.succ # => "10a\xFFa0"
+ *
+ *  The successor to an empty \String is a new empty \String:
+ *    ''.succ # => ""
  */
 
 VALUE

From f9ea5e20e04ae01ea22c2e47d89c379d495de586 Mon Sep 17 00:00:00 2001
From: BurdetteLamar <burdettelamar@yahoo.com>
Date: Fri, 25 Sep 2020 14:28:55 -0500
Subject: [PATCH 2/2] Enhanced RDoc for String#succ

---
 string.c | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/string.c b/string.c
index b23dddb7b7141a..cf25dc1861b328 100644
--- a/string.c
+++ b/string.c
@@ -4161,7 +4161,6 @@ static VALUE str_succ(VALUE str);
 /*
  *  call-seq:
  *    string.succ -> new_str
- *    string.next -> new_str
  *
  *  Returns the successor to +self+. The successor is calculated by
  *  incrementing characters.
@@ -4200,19 +4199,16 @@ static VALUE str_succ(VALUE str);
  *    s # => "\xFF\xFF\xFF"
  *    s.succ # => "\x01\x00\x00\x00"
  *
- *  Carrying can occur between and among all types of characters:
- *    s = format("%s%s%s%s%s", 255.chr, '9', 'z', '9', 255.chr)
- *    s # => "\xFF9z9\xFF"
- *    s.succ # => "\xFF10a0\xFF"
- *    s = format("%s%s%s%s%s", 'z', 255.chr, '9', 255.chr, 'z')
- *    s # => "z\xFF9\xFFz"
- *    s.succ # => "z\xFF9\xFFaa"
- *    s = format("%s%s%s%s%s", '9', 'z', 255.chr, 'z', '9')
- *    s # => "9z\xFFz9"
- *    s.succ # => "10a\xFFa0"
+ *  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 # => ""
+ *
+ *  String#next is an alias for String#succ.
  */
 
 VALUE