[DOC] Enhanced RDoc for String#split (#5644)

* Enhanced RDoc for String#split

* Enhanced RDoc for String#split

* Enhanced RDoc for String#split

* Enhanced RDoc for String#split

* Enhanced RDoc for String#split

1 files changed, 92 insertions, 0 deletions

diff --git a/doc/string.rdoc b/doc/string.rdoc
index c9fa0607f3..6c3ced298a 100644
--- a/doc/string.rdoc
+++ b/doc/string.rdoc
@@ -47,4 +47,96 @@ class String
   def initialize(str = '', encoding: nil, capacity: nil)
     Primitive.rb_str_init(str, encoding, capacity)
   end
+
+  #  call-seq:
+  #    split(separator = $;, limit = nil) -> array
+  #    split(separator = $;, 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+.
+  #
+  #  When argument +separator+ is <tt>$;</tt>:
+  #
+  #  - If <tt>$;</tt> is +nil+ (its default value),
+  #    the split occurs just as if +separator+ 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
+  #    (see below).
+  #
+  #  When argument +separator+ is <tt>' '</tt> and argument +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;
+  #  trailing empty substrings are not returned:
+  #
+  #    'abracadabra'.split('ab')   # => ["", "racad", "ra"]
+  #    'aaabcdaaa'.split('a')      # => ["", "", "", "bcd"]
+  #    ''.split('a')               # => []
+  #    '3.14159'.split('1')        # => ["3.", "4", "59"]
+  #    '!@#$%^$&*($)_+'.split('$') # => ["!@#", "%^", "&*(", ")_+"]
+  #    'тест'.split('т')           # => ["", "ес"]
+  #    'こんにちは'.split('に')      # => ["こん", "ちは"]
+  #
+  #  When argument +separator+ is a Regexp and argument +limit+ is +nil+,
+  #  the split occurs at each occurrence of a match;
+  #  trailing empty substrings are not returned:
+  #
+  #    'abracadabra'.split(/ab/) # => ["", "racad", "ra"]
+  #    'aaabcdaaa'.split(/a/)    # => ["", "", "", "bcd"]
+  #    'aaabcdaaa'.split(//)     # => ["a", "a", "a", "b", "c", "d", "a", "a", "a"]
+  #    '1 + 1 == 2'.split(/\W+/) # => ["1", "1", "2"]
+  #
+  #  If the \Regexp contains groups, their matches are also included
+  #  in the returned array:
+  #
+  #    '1:2:3'.split(/(:)()()/, 2) # => ["1", ":", "", "", "2:3"]
+  #
+  #  As seen above, if argument +limit+ is +nil+,
+  #  trailing empty substrings are not returned;
+  #  the same is true if +limit+ is zero:
+  #
+  #    'aaabcdaaa'.split('a')    # => ["", "", "", "bcd"]
+  #    'aaabcdaaa'.split('a', 0) # => ["", "", "", "bcd"]
+  #
+  #  If +limit+ is positive integer +n+, no more than <tt>n - 1-</tt>
+  #  splits occur, so that at most +n+ substrings are returned,
+  #  and trailing empty substrings are included:
+  #
+  #    'aaabcdaaa'.split('a', 1) # => ["aaabcdaaa"]
+  #    'aaabcdaaa'.split('a', 2) # => ["", "aabcdaaa"]
+  #    'aaabcdaaa'.split('a', 5) # => ["", "", "", "bcd", "aa"]
+  #    'aaabcdaaa'.split('a', 7) # => ["", "", "", "bcd", "", "", ""]
+  #    'aaabcdaaa'.split('a', 8) # => ["", "", "", "bcd", "", "", ""]
+  #
+  #  Note that if +separator+ 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+,
+  #  meaning that there is no limit,
+  #  and trailing empty substrings are included:
+  #
+  #    'aaabcdaaa'.split('a', -1) # => ["", "", "", "bcd", "", "", ""]
+  #
+  #  If a block is given, it is called with each substring:
+  #
+  #    'abc def ghi'.split(' ') {|substring| p substring }
+  #
+  #  Output:
+  #
+  #    "abc"
+  #    "def"
+  #    "ghi"
+  #
+  def split; end
+
 end