Swap documentation for String#split array and block versions. (#12808)

src/string.cr

@@ -3947,7 +3947,7 @@ class String
     yield String.new(to_unsafe + byte_offset, piece_bytesize, piece_size)
   end
 
-  # Splits the string after each regex *separator* and yields each part to a block.
+  # Makes an `Array` by splitting the string on *separator* (and removing instances of *separator*).
   #
   # If *limit* is present, the array will be limited to *limit* items and
   # the final item will contain the remainder of the string.
@@ -3957,15 +3957,9 @@ class String
   # If *remove_empty* is `true`, any empty strings are removed from the result.
   #
   # ```
-  # ary = [] of String
   # long_river_name = "Mississippi"
-  #
-  # long_river_name.split(/s+/) { |s| ary << s }
-  # ary # => ["Mi", "i", "ippi"]
-  # ary.clear
-  #
-  # long_river_name.split(//) { |s| ary << s }
-  # ary # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
+  # long_river_name.split(/s+/) # => ["Mi", "i", "ippi"]
+  # long_river_name.split(//)   # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
   # ```
   def split(separator : Regex, limit = nil, *, remove_empty = false) : Array(String)
     ary = Array(String).new
@@ -3975,7 +3969,7 @@ class String
     ary
   end
 
-  # Makes an `Array` by splitting the string on *separator* (and removing instances of *separator*).
+  # Splits the string after each regex *separator* and yields each part to a block.
   #
   # If *limit* is present, the array will be limited to *limit* items and
   # the final item will contain the remainder of the string.
@@ -3985,9 +3979,15 @@ class String
   # If *remove_empty* is `true`, any empty strings are removed from the result.
   #
   # ```
+  # ary = [] of String
   # long_river_name = "Mississippi"
-  # long_river_name.split(/s+/) # => ["Mi", "i", "ippi"]
-  # long_river_name.split(//)   # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
+  #
+  # long_river_name.split(/s+/) { |s| ary << s }
+  # ary # => ["Mi", "i", "ippi"]
+  # ary.clear
+  #
+  # long_river_name.split(//) { |s| ary << s }
+  # ary # => ["M", "i", "s", "s", "i", "s", "s", "i", "p", "p", "i"]
   # ```
   def split(separator : Regex, limit = nil, *, remove_empty = false, &block : String -> _)
     if empty?