Improve Enum.chunk_while/4 docs to clarify after_fun semantics (#10595)

- add `{:halt, acc}` tuple return doc for `chunk_fun`
- explain `after_fun` semantics in more detail
- format return tuples for `chunk_fun` and `after_fun` as markdown lists
- added note that `acc` in `after_fun` return tuple is ignored
- note that `Enum.chunk_while/4` returns a list of *chunks*, not a list
  of lists (emitted chunks can be anything, not necessarily just lists)

Author: madlep

lib/elixir/lib/enum.ex

@@ -473,15 +473,25 @@ defmodule Enum do
   @doc """
   Chunks the `enumerable` with fine grained control when every chunk is emitted.
 
-  `chunk_fun` receives the current element and the accumulator and
-  must return `{:cont, chunk, acc}` to emit the given chunk and
-  continue with accumulator or `{:cont, acc}` to not emit any chunk
-  and continue with the return accumulator.
+  `chunk_fun` receives the current element and the accumulator and must return:
 
-  `after_fun` is invoked when iteration is done and must also return
-  `{:cont, chunk, acc}` or `{:cont, acc}`.
+    * `{:cont, chunk, acc}` to emit a chunk and continue with the accumulator
+    * `{:cont, acc}` to not emit any chunk and continue with the accumulator
+    * `{:halt, acc}` to halt chunking over the `enumerable`.
 
-  Returns a list of lists.
+  `after_fun` is invoked with the final accumulator when iteration is
+  finished (or `halt`ed) to handle any trailing elements that were returned
+  as part of an accumulator, but were not emited as a chunk by `chunk_fun`.
+  It must return:
+
+    * `{:cont, chunk, acc}` to emit a chunk. The chunk will be appended to the
+      list of already emitted chunks.
+    * `{:cont, acc}` to not emit a chunk
+
+  The `acc` in `after_fun` is required in order to mirror the tuple format
+  from `chunk_fun` but it will be discarded since the traversal is complete.
+
+  Returns a list of emitted chunks.
 
   ## Examples
 
@@ -498,6 +508,8 @@ defmodule Enum do
       ...> end
       iex> Enum.chunk_while(1..10, [], chunk_fun, after_fun)
       [[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
+      iex> Enum.chunk_while([1, 2, 3, 5, 7], [], chunk_fun, after_fun)
+      [[1, 2], [3, 5, 7]]
 
   """
   @doc since: "1.5.0"
@@ -512,15 +524,15 @@ defmodule Enum do
     {_, {res, acc}} =
       Enumerable.reduce(enumerable, {:cont, {[], acc}}, fn entry, {buffer, acc} ->
         case chunk_fun.(entry, acc) do
-          {:cont, emit, acc} -> {:cont, {[emit | buffer], acc}}
+          {:cont, chunk, acc} -> {:cont, {[chunk | buffer], acc}}
           {:cont, acc} -> {:cont, {buffer, acc}}
           {:halt, acc} -> {:halt, {buffer, acc}}
         end
       end)
 
     case after_fun.(acc) do
       {:cont, _acc} -> :lists.reverse(res)
-      {:cont, elem, _acc} -> :lists.reverse([elem | res])
+      {:cont, chunk, _acc} -> :lists.reverse([chunk | res])
     end
   end
 

lib/elixir/test/elixir/enum_test.exs

@@ -116,6 +116,17 @@ defmodule EnumTest do
              [[0], [1, 2], [3, 4], [5, 6], [7, 8], [9, 10]]
 
     assert Enum.chunk_while([5, 7, 9, 11], [], chunk_fun, after_fun) == [[5, 7, 9]]
+
+    assert Enum.chunk_while([1, 2, 3, 5, 7], [], chunk_fun, after_fun) == [[1, 2], [3, 5, 7]]
+
+    chunk_fn2 = fn
+      -1, acc -> {:cont, acc, 0}
+      i, acc -> {:cont, acc + i}
+    end
+
+    after_fn2 = fn acc -> {:cont, acc, 0} end
+
+    assert Enum.chunk_while([1, -1, 2, 3, -1, 4, 5, 6], 0, chunk_fn2, after_fn2) == [1, 5, 15]
   end
 
   test "concat/1" do