[DOC] Enhanced RDoc for String (#5675)

Treats:
    #split
    #each_line
    #lines
    #each_byte
    #bytes

doc/string.rdoc

@@ -49,34 +49,137 @@ class String
   end
 
   #  call-seq:
-  #    split(separator = $;, limit = nil) -> array
-  #    split(separator = $;, limit = nil) {|substring| ... } -> self
+  #    bytes -> array_of_bytes
+  #
+  #  Returns an array of the bytes in +self+:
+  #
+  #    'hello'.bytes # => [104, 101, 108, 108, 111]
+  #    'тест'.bytes  # => [209, 130, 208, 181, 209, 129, 209, 130]
+  #    'こんにちは'.bytes
+  #    # => [227, 129, 147, 227, 130, 147, 227, 129, 171, 227, 129, 161, 227, 129, 175]
+  #
+  def bytes; end
+
+  #  call-seq:
+  #    each_byte {|byte| ... } -> self
+  #    each_byte               -> enumerator
+  #
+  #  Calls the given block with each successive byte from +self+;
+  #  returns +self+:
+  #
+  #    'hello'.each_byte {|byte| print byte, ' ' }
+  #    print "\n"
+  #    'тест'.each_byte {|byte| print byte, ' ' }
+  #    print "\n"
+  #    'こんにちは'.each_byte {|byte| print byte, ' ' }
+  #    print "\n"
+  #
+  #  Output:
+  #
+  #    104 101 108 108 111
+  #    209 130 208 181 209 129 209 130
+  #    227 129 147 227 130 147 227 129 171 227 129 161 227 129 175
+  #
+  #  Returns an enumerator if no block is given.
+  def each_byte; end
+
+
+  #  call-seq:
+  #    each_line(line_sep = $/, chomp: false) {|substring| ... } -> self
+  #    each_line(line_sep = $/, chomp: false)                    -> enumerator
+  #
+  #  With a block given, forms the substrings ("lines")
+  #  that are the result of splitting +self+
+  #  at each occurrence of the given line separator +line_sep+;
+  #  passes each line to the block;
+  #  returns +self+:
+  #
+  #    s = <<~EOT
+  #    This is the first line.
+  #    This is line two.
+  #
+  #    This is line four.
+  #    This is line five.
+  #    EOT
+  #
+  #    s.each_line {|line| p line }
+  #
+  #  Output:
+  #
+  #    "This is the first line.\n"
+  #    "This is line two.\n"
+  #    "\n"
+  #    "This is line four.\n"
+  #    "This is line five.\n"
+  #
+  #  With a different +line_sep+:
+  #
+  #    s.each_line(' is ') {|line| p line }
+  #
+  #  Output:
+  #
+  #    "This is "
+  #    "the first line.\nThis is "
+  #    "line two.\n\nThis is "
+  #    "line four.\nThis is "
+  #    "line five.\n"
+  #
+  #  With +chomp+ as +true+, removes the trailing +line_sep+ from each line:
+  #
+  #    s.each_line(chomp: true) {|line| p line }
+  #
+  #  Output:
+  #
+  #    "This is the first line."
+  #    "This is line two."
+  #    ""
+  #    "This is line four."
+  #    "This is line five."
+  #
+  #  With an empty string as +line_sep+,
+  #  forms and passes "paragraphs" by splitting at each occurrence
+  #  of two or more newlines:
+  #
+  #    s.each_line('') {|line| p line }
+  #
+  #  Output:
+  #
+  #    "This is the first line.\nThis is line two.\n\n"
+  #    "This is line four.\nThis is line five.\n"
+  #
+  #  With no block given, returns an enumerator.
+  #
+  def each_line; end
+
+  #  call-seq:
+  #    split(field_sep = $;, limit = nil) -> array
+  #    split(field_sep = $;, limit = nil) {|substring| ... } -> self
   #
   #  Returns an array of substrings of +self+
   #  that are the result of splitting +self+
-  #  at each occurrence of the given +separator+.
+  #  at each occurrence of the given field separator +field_sep+.
   #
-  #  When argument +separator+ is <tt>$;</tt>:
+  #  When +field_sep+ is <tt>$;</tt>:
   #
   #  - If <tt>$;</tt> is +nil+ (its default value),
-  #    the split occurs just as if +separator+ were given as a space character
+  #    the split occurs just as if +field_sep+ were given as a space character
   #    (see below).
   #
   #  - If <tt>$;</tt> is a string,
-  #    the split ocurs just as if +separator+ were given as that string
+  #    the split ocurs just as if +field_sep+ were given as that string
   #    (see below).
   #
-  #  When argument +separator+ is <tt>' '</tt> and argument +limit+ is +nil+,
+  #  When +field_sep+ is <tt>' '</tt> and +limit+ is +nil+,
   #  the split occurs at each sequence of whitespace:
   #
   #    'abc def ghi'.split(' ')          # => ["abc", "def", "ghi"]
   #    "abc \n\tdef\t\n  ghi".split(' ') # => ["abc", "def", "ghi"]
   #    'abc  def   ghi'.split(' ')       # => ["abc", "def", "ghi"]
   #    ''.split(' ')                     # => []
   #
-  #  When argument +separator+ is a string different from <tt>' '</tt>
-  #  and argument +limit+ is +nil+,
-  #  the split occurs at each occurrence of the separator;
+  #  When +field_sep+ is a string different from <tt>' '</tt>
+  #  and +limit+ is +nil+,
+  #  the split occurs at each occurrence of +field_sep+;
   #  trailing empty substrings are not returned:
   #
   #    'abracadabra'.split('ab')   # => ["", "racad", "ra"]
@@ -87,7 +190,7 @@ class String
   #    'тест'.split('т')           # => ["", "ес"]
   #    'こんにちは'.split('に')      # => ["こん", "ちは"]
   #
-  #  When argument +separator+ is a Regexp and argument +limit+ is +nil+,
+  #  When +field_sep+ is a Regexp and +limit+ is +nil+,
   #  the split occurs at each occurrence of a match;
   #  trailing empty substrings are not returned:
   #
@@ -101,7 +204,7 @@ class String
   #
   #    '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"]
   #
-  #  As seen above, if argument +limit+ is +nil+,
+  #  As seen above, if +limit+ is +nil+,
   #  trailing empty substrings are not returned;
   #  the same is true if +limit+ is zero:
   #
@@ -118,7 +221,7 @@ class String
   #    'aaabcdaaa'.split('a', 7) # => ["", "", "", "bcd", "", "", ""]
   #    'aaabcdaaa'.split('a', 8) # => ["", "", "", "bcd", "", "", ""]
   #
-  #  Note that if +separator+ is a \Regexp containing groups,
+  #  Note that if +field_sep+ is a \Regexp containing groups,
   #  their matches are in the returned array, but do not count toward the limit.
   #
   #  If +limit+ is negative, it behaves the same as if +limit+ was +nil+,

string.c

@@ -8652,9 +8652,7 @@ literal_split_pattern(VALUE spat, split_type_t default_type)
     return default_type;
 }
 
-/*
- * String#split is documented at doc/string.rdoc.
- */
+// String#split is documented at doc/string.rdoc.
 
 static VALUE
 rb_str_split_m(int argc, VALUE *argv, VALUE str)
@@ -9065,52 +9063,7 @@ rb_str_enumerate_lines(int argc, VALUE *argv, VALUE str, VALUE ary)
 	return orig;
 }
 
-/*
- *  call-seq:
- *     str.each_line(separator=$/, chomp: false) {|substr| block } -> str
- *     str.each_line(separator=$/, chomp: false)                   -> an_enumerator
- *
- *  Splits <i>str</i> using the supplied parameter as the record
- *  separator (<code>$/</code> by default), passing each substring in
- *  turn to the supplied block.  If a zero-length record separator is
- *  supplied, the string is split into paragraphs delimited by
- *  multiple successive newlines.
- *
- *  If +chomp+ is +true+, +separator+ will be removed from the end of each
- *  line.
- *
- *  If no block is given, an enumerator is returned instead.
- *
- *     "hello\nworld".each_line {|s| p s}
- *     # prints:
- *     #   "hello\n"
- *     #   "world"
- *
- *     "hello\nworld".each_line('l') {|s| p s}
- *     # prints:
- *     #   "hel"
- *     #   "l"
- *     #   "o\nworl"
- *     #   "d"
- *
- *     "hello\n\n\nworld".each_line('') {|s| p s}
- *     # prints
- *     #   "hello\n\n"
- *     #   "world"
- *
- *     "hello\nworld".each_line(chomp: true) {|s| p s}
- *     # prints:
- *     #   "hello"
- *     #   "world"
- *
- *     "hello\nworld".each_line('l', chomp: true) {|s| p s}
- *     # prints:
- *     #   "he"
- *     #   ""
- *     #   "o\nwor"
- *     #   "d"
- *
- */
+// String#each_line is documented at doc/string.rdoc.
 
 static VALUE
 rb_str_each_line(int argc, VALUE *argv, VALUE str)
@@ -9121,21 +9074,11 @@ rb_str_each_line(int argc, VALUE *argv, VALUE str)
 
 /*
  *  call-seq:
- *     str.lines(separator=$/, chomp: false)  -> an_array
- *
- *  Returns an array of lines in <i>str</i> split using the supplied
- *  record separator (<code>$/</code> by default).  This is a
- *  shorthand for <code>str.each_line(separator, getline_args).to_a</code>.
+ *    lines(Line_sep = $/, chomp: false) -> array_of_strings
  *
- *  If +chomp+ is +true+, +separator+ will be removed from the end of each
- *  line.
+ *  Forms substrings ("lines") of +self+ according to the given arguments
+ *  (see String#each_line for details); returns the lines in an array.
  *
- *     "hello\nworld\n".lines              #=> ["hello\n", "world\n"]
- *     "hello  world".lines(' ')           #=> ["hello ", " ", "world"]
- *     "hello\nworld\n".lines(chomp: true) #=> ["hello", "world"]
- *
- *  If a block is given, which is a deprecated form, works the same as
- *  <code>each_line</code>.
  */
 
 static VALUE
@@ -9165,20 +9108,7 @@ rb_str_enumerate_bytes(VALUE str, VALUE ary)
 	return str;
 }
 
-/*
- *  call-seq:
- *     str.each_byte {|integer| block }    -> str
- *     str.each_byte                      -> an_enumerator
- *
- *  Passes each byte in <i>str</i> to the given block, or returns an
- *  enumerator if no block is given.
- *
- *     "hello".each_byte {|c| print c, ' ' }
- *
- *  <em>produces:</em>
- *
- *     104 101 108 108 111
- */
+// String#each_byte is documented in doc/string.rdoc.
 
 static VALUE
 rb_str_each_byte(VALUE str)
@@ -9187,16 +9117,7 @@ rb_str_each_byte(VALUE str)
     return rb_str_enumerate_bytes(str, 0);
 }
 
-/*
- *  call-seq:
- *     str.bytes    -> an_array
- *
- *  Returns an array of bytes in <i>str</i>.  This is a shorthand for
- *  <code>str.each_byte.to_a</code>.
- *
- *  If a block is given, which is a deprecated form, works the same as
- *  <code>each_byte</code>.
- */
+// String#bytes is documented in doc/string.rdoc.
 
 static VALUE
 rb_str_bytes(VALUE str)