   end
 
   @doc """
-  Splits the given keywords in two given the given keys.
-  Duplicated keys are preserved in the split keyword list.
+  Takes all entries corresponding to the given keys and extracts them into a
+  separate keyword list. Returns a tuple with the new list and the old list
+  with removed keys.
+
+  Keys for which there are no entires in the keyword list are ignored.
+
+  Entries with duplicated keys end up in the same keyword list.
 
   ## Examples
 

      iex> Keyword.drop(d, [:b, :d])
      [a: 1, c: 3]

      iex> d = [a: 1, b: 2, c: 3, d: 4, a: 5]
      iex> Keyword.drop(d, [:b, :d])
      [a: 1, c: 3, a: 5]


  end

  @doc """
  Takes all entries corresponding to the given keys and returns them in a new
  keyword list.

  Duplicated keys are preserved in the new keyword list.

  ## Examples
