   end
 
   @doc """
-  Invokes the given `fun` for each item in the `collection`.
-  Returns only the items the function evalutes to true.
+  Filters the collection, i.e. returns only those elements
+  for which `fun` returns true.
 
   ## Examples
 

  require Enum.Iterator, as: I

  @moduledoc """
  Evalutes the items in the given collection according to the
  Enum.Iterator protocol. Most functions in this module
  will automatically retrieve the protocol given the collection
  and iterator, for example:

      Enum.map [1,2,3], fun(x, do: x * 2)

  However, one can use their own iteration function for any
  collection by passing their own iterator function with the
  head of iteration:

      current = my_iteration_function.([1,2,3)
      Enum.map my_iteration_function, current, fun(x, do: x * 2)

  ## The protocol

  When `Enum.map` is invoked without the iterator function,
  it invokes `Enum.Iterator.iterator(collection)` with the
  given collection in order to retrieve the default iterator
  for that collection. You can implement the protocol for any
  data type you wish. Elixir ships with a default iterator
  for lists, implemented as follow:

      defimpl Enum.Iterator, for: List do
        def iterator(list), do: { iterate(&1), iterate(list) }


  @doc """
  Iterates the given function n times, passing values from 1
  to n. Also has an accumulator similar to reduce to store the
  value between computations.

  ## Examples
