Add clarity to docs and doctests

Author: dmitrykleymenov

lib/elixir/lib/enum.ex

@@ -3924,8 +3924,9 @@ defmodule Enum do
   If an integer offset is given as `fun_or_offset`, it will index from the given
   offset instead of from zero.
 
-  If a function is given as `fun_or_offset`, it will index by invoking the function
-  for each element and index (zero-based) of the enumerable.
+  If a 2-arity function is given as `fun_or_offset`, the function will be invoked
+  for each element in `enumerable` as the first argument and with a zero-based
+  index as the second. The result of the invocation will be listed.
 
   ## Examples
 
@@ -4036,10 +4037,10 @@ defmodule Enum do
   key in the left map and the matching key in the right map, but there is no such
   guarantee because map keys are not ordered! Consider the following:
 
-      left =  %{:a => 1, 1 => 3}
-      right = %{:a => 1, :b => :c}
-      Enum.zip(left, right)
-      # [{{1, 3}, {:a, 1}}, {{:a, 1}, {:b, :c}}]
+      iex> left = %{:a => 1, 1 => 3}
+      iex> right = %{:a => 1, :b => :c}
+      iex> Enum.zip(left, right)
+      [{{1, 3}, {:a, 1}}, {{:a, 1}, {:b, :c}}]
 
   As you can see `:a` does not get paired with `:a`. If this is what you want,
   you should use `Map.merge/3`.
@@ -4109,11 +4110,11 @@ defmodule Enum do
 
   ## Examples
 
-      iex> Enum.zip_reduce([1, 2], [3, 4], 0, fn x, y, acc -> x + y + acc end)
+      iex> Enum.zip_reduce([1, 2], [3, 4, 5], 0, fn x, y, acc -> x + y + acc end)
       10
 
-      iex> Enum.zip_reduce([1, 2], [3, 4], [], fn x, y, acc -> [x + y | acc] end)
-      [6, 4]
+      iex> Enum.zip_reduce([1, 2, 3], [4, 5], [], fn x, y, acc -> [x + y | acc] end)
+      [7, 5]
   """
   @doc since: "1.12.0"
   @spec zip_reduce(t, t, acc, (enum1_elem :: term, enum2_elem :: term, acc -> acc)) :: acc
@@ -4143,13 +4144,13 @@ defmodule Enum do
 
   ## Examples
 
-      iex> enums = [[1, 1], [2, 2], [3, 3]]
+      iex> enums = [[1, 1, 1, 1], [2, 2, 2], [3, 3]]
       ...>  Enum.zip_reduce(enums, [], fn elements, acc ->
       ...>    [List.to_tuple(elements) | acc]
       ...> end)
       [{1, 2, 3}, {1, 2, 3}]
 
-      iex> enums = [[1, 2], [a: 3, b: 4], [5, 6]]
+      iex> enums = [[1, 2], [a: 3, b: 4], [5, 6, 7]]
       ...> Enum.zip_reduce(enums, [], fn elements, acc ->
       ...>   [List.to_tuple(elements) | acc]
       ...> end)