Revert flawed doc for slice_after, slice_when, and chunk_while (#5952)

Restores doc for the methods that were cited in https://bugs.ruby-lang.org/issues/18765.

1 files changed, 107 insertions, 55 deletions

diff --git a/enum.c b/enum.c
index 403ce45dca..205ea6a451 100644
--- a/enum.c
+++ b/enum.c
@@ -4079,39 +4079,24 @@ sliceafter_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator))
 
 /*
  *  call-seq:
- *    slice_after(pattern)       -> enumerator
- *    slice_after {|array| ... } -> enumerator
+ *     enum.slice_after(pattern)       -> an_enumerator
+ *     enum.slice_after { |elt| bool } -> an_enumerator
  *
- *  With argument +pattern+, returns an enumerator that uses the pattern
- *  to partition elements into arrays ("slices").
- *  An element ends the current slice if <tt>element === pattern</tt>:
+ *  Creates an enumerator for each chunked elements.
+ *  The ends of chunks are defined by _pattern_ and the block.
  *
- *    a = %w[foo bar fop for baz fob fog bam foy]
- *    e = a.slice_after(/ba/) # => #<Enumerator: ...>
- *    e.each {|array| p array }
+ *  If <code>_pattern_ === _elt_</code> returns <code>true</code> or the block
+ *  returns <code>true</code> for the element, the element is end of a
+ *  chunk.
  *
- *  Output:
+ *  The <code>===</code> and _block_ is called from the first element to the last
+ *  element of _enum_.
  *
- *    ["foo", "bar"]
- *    ["fop", "for", "baz"]
- *    ["fob", "fog", "bam"]
- *    ["foy"]
+ *  The result enumerator yields the chunked elements as an array.
+ *  So +each+ method can be called as follows:
  *
- *  With a block, returns an enumerator that uses the block
- *  to partition elements into arrays.
- *  An element ends the current slice if its block return is a truthy value:
- *
- *    e = (1..20).slice_after {|i| i % 4 == 2 } # => #<Enumerator: ...>
- *    e.each {|array| p array }
- *
- *  Output:
- *
- *    [1, 2]
- *    [3, 4, 5, 6]
- *    [7, 8, 9, 10]
- *    [11, 12, 13, 14]
- *    [15, 16, 17, 18]
- *    [19, 20]
+ *    enum.slice_after(pattern).each { |ary| ... }
+ *    enum.slice_after { |elt| bool }.each { |ary| ... }
  *
  *  Other methods of the Enumerator class and Enumerable module,
  *  such as +map+, etc., are also usable.
@@ -4225,23 +4210,65 @@ slicewhen_i(RB_BLOCK_CALL_FUNC_ARGLIST(yielder, enumerator))
 
 /*
  *  call-seq:
- *    slice_when {|element, next_element| ... } -> enumerator
+ *     enum.slice_when {|elt_before, elt_after| bool } -> an_enumerator
  *
- *  The returned enumerator uses the block
- *  to partition elements into arrays ("slices");
- *  it calls the block with each element and its successor;
- *  begins a new slice if and only if the block returns a truthy value:
+ *  Creates an enumerator for each chunked elements.
+ *  The beginnings of chunks are defined by the block.
  *
- *    a = [0, 1, 2, 4, 5, 6, 8, 9]
- *    e = a.slice_when {|i, j| j != i + 1 }
- *    e.each {|array| p array }
+ *  This method splits each chunk using adjacent elements,
+ *  _elt_before_ and _elt_after_,
+ *  in the receiver enumerator.
+ *  This method split chunks between _elt_before_ and _elt_after_ where
+ *  the block returns <code>true</code>.
  *
- *  Output:
+ *  The block is called the length of the receiver enumerator minus one.
+ *
+ *  The result enumerator yields the chunked elements as an array.
+ *  So +each+ method can be called as follows:
+ *
+ *    enum.slice_when { |elt_before, elt_after| bool }.each { |ary| ... }
+ *
+ *  Other methods of the Enumerator class and Enumerable module,
+ *  such as +to_a+, +map+, etc., are also usable.
+ *
+ *  For example, one-by-one increasing subsequence can be chunked as follows:
  *
- *    [0, 1, 2]
- *    [4, 5, 6]
- *    [8, 9]
+ *    a = [1,2,4,9,10,11,12,15,16,19,20,21]
+ *    b = a.slice_when {|i, j| i+1 != j }
+ *    p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]]
+ *    c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" }
+ *    p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"]
+ *    d = c.join(",")
+ *    p d #=> "1,2,4,9-12,15,16,19-21"
  *
+ *  Near elements (threshold: 6) in sorted array can be chunked as follows:
+ *
+ *    a = [3, 11, 14, 25, 28, 29, 29, 41, 55, 57]
+ *    p a.slice_when {|i, j| 6 < j - i }.to_a
+ *    #=> [[3], [11, 14], [25, 28, 29, 29], [41], [55, 57]]
+ *
+ *  Increasing (non-decreasing) subsequence can be chunked as follows:
+ *
+ *    a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5]
+ *    p a.slice_when {|i, j| i > j }.to_a
+ *    #=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]]
+ *
+ *  Adjacent evens and odds can be chunked as follows:
+ *  (Enumerable#chunk is another way to do it.)
+ *
+ *    a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0]
+ *    p a.slice_when {|i, j| i.even? != j.even? }.to_a
+ *    #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]]
+ *
+ *  Paragraphs (non-empty lines with trailing empty lines) can be chunked as follows:
+ *  (See Enumerable#chunk to ignore empty lines.)
+ *
+ *    lines = ["foo\n", "bar\n", "\n", "baz\n", "qux\n"]
+ *    p lines.slice_when {|l1, l2| /\A\s*\z/ =~ l1 && /\S/ =~ l2 }.to_a
+ *    #=> [["foo\n", "bar\n", "\n"], ["baz\n", "qux\n"]]
+ *
+ *  Enumerable#chunk_while does the same, except splitting when the block
+ *  returns <code>false</code> instead of <code>true</code>.
  */
 static VALUE
 enum_slice_when(VALUE enumerable)
@@ -4262,27 +4289,52 @@ enum_slice_when(VALUE enumerable)
 
 /*
  *  call-seq:
- *    chunk_while {|element, next_element| ... } -> enumerator
+ *     enum.chunk_while {|elt_before, elt_after| bool } -> an_enumerator
  *
- *  The returned Enumerator uses the block to partition elements
- *  into arrays ("chunks");
- *  it calls the block with each element and its successor;
- *  begins a new chunk if and only if the block returns a truthy value:
+ *  Creates an enumerator for each chunked elements.
+ *  The beginnings of chunks are defined by the block.
  *
- *  Example:
+ *  This method splits each chunk using adjacent elements,
+ *  _elt_before_ and _elt_after_,
+ *  in the receiver enumerator.
+ *  This method split chunks between _elt_before_ and _elt_after_ where
+ *  the block returns <code>false</code>.
  *
- *    a = [1, 2, 4, 9, 10, 11, 12, 15, 16, 19, 20, 21]
- *    e = a.chunk_while {|i, j| j == i + 1 }
- *    e.each {|array| p array }
+ *  The block is called the length of the receiver enumerator minus one.
  *
- *  Output:
+ *  The result enumerator yields the chunked elements as an array.
+ *  So +each+ method can be called as follows:
  *
- *    [1, 2]
- *    [4]
- *    [9, 10, 11, 12]
- *    [15, 16]
- *    [19, 20, 21]
+ *    enum.chunk_while { |elt_before, elt_after| bool }.each { |ary| ... }
+ *
+ *  Other methods of the Enumerator class and Enumerable module,
+ *  such as +to_a+, +map+, etc., are also usable.
+ *
+ *  For example, one-by-one increasing subsequence can be chunked as follows:
+ *
+ *    a = [1,2,4,9,10,11,12,15,16,19,20,21]
+ *    b = a.chunk_while {|i, j| i+1 == j }
+ *    p b.to_a #=> [[1, 2], [4], [9, 10, 11, 12], [15, 16], [19, 20, 21]]
+ *    c = b.map {|a| a.length < 3 ? a : "#{a.first}-#{a.last}" }
+ *    p c #=> [[1, 2], [4], "9-12", [15, 16], "19-21"]
+ *    d = c.join(",")
+ *    p d #=> "1,2,4,9-12,15,16,19-21"
+ *
+ *  Increasing (non-decreasing) subsequence can be chunked as follows:
+ *
+ *    a = [0, 9, 2, 2, 3, 2, 7, 5, 9, 5]
+ *    p a.chunk_while {|i, j| i <= j }.to_a
+ *    #=> [[0, 9], [2, 2, 3], [2, 7], [5, 9], [5]]
+ *
+ *  Adjacent evens and odds can be chunked as follows:
+ *  (Enumerable#chunk is another way to do it.)
+ *
+ *    a = [7, 5, 9, 2, 0, 7, 9, 4, 2, 0]
+ *    p a.chunk_while {|i, j| i.even? == j.even? }.to_a
+ *    #=> [[7, 5, 9], [2, 0], [7, 9], [4, 2, 0]]
  *
+ *  Enumerable#slice_when does the same, except splitting when the block
+ *  returns <code>true</code> instead of <code>false</code>.
  */
 static VALUE
 enum_chunk_while(VALUE enumerable)