diff --git a/lib/elixir/lib/option_parser.ex b/lib/elixir/lib/option_parser.ex
index 1ff5b7aa0ea..3904656b102 100644
--- a/lib/elixir/lib/option_parser.ex
+++ b/lib/elixir/lib/option_parser.ex
@@ -1,7 +1,11 @@
 defmodule OptionParser do
+  @moduledoc """
+  This module contains functions to parse command line arguments.
+  """
+
   @doc """
-  Parses the argv and returns one tuple with parsed options
-  and the arguments.
+  Parses `argv` and returns a tuple with parsed options
+  and arguments.
 
   ## Examples
 
@@ -16,22 +20,22 @@ defmodule OptionParser do
 
   ## Aliases
 
-  A set of aliases can be given as second argument:
+  A set of aliases can be given as the second argument:
 
       iex> OptionParser.parse(["-d"], aliases: [d: :debug])
       { [debug: true], [] }
 
   ## Switches
 
-  Extra information about switches can be given as argument too.
-  This is useful in order to say a switch must behave as a boolean
+  Extra information about switches can be given as arguments, too.
+  This is useful when a switch must behave as a boolean
   or if duplicated switches should be kept, overriden or accumulated.
 
   The following types are supported:
 
-  * `:boolean` - Marks the given switch as boolean. Boolean switches
-                 never consumes the following value unless it is
-                 true or false;
+  * `:boolean` - Marks the given switch as a boolean. Boolean switches
+                 never consume the following value unless it is
+                 `true` or `false`;
   * `:integer` - Parses the switch as an integer;
   * `:float`   - Parses the switch as a float;
 
@@ -61,16 +65,18 @@ defmodule OptionParser do
   end
 
   @doc """
-  Similar to parse but only parses the head of the argv.
-  I.e. as soon as it finds a non switch, it stops parsing.
+  Similar to `parse/2` but only parses the head of `argv`;
+  as soon as it finds a non-switch, it stops parsing.
 
-  Check `parse/2` for more info.
+  See `parse/2` for more information.
 
   ## Example
 
       iex> OptionParser.parse_head(["--source", "lib", "test/enum_test.exs", "--verbose"])
       { [source: "lib"], ["test/enum_test.exs", "--verbose"] }
 
+      iex> OptionParser.parse_head(["--verbose", "--source", "lib", "test/enum_test.exs", "--unlock"])
+      {[verbose: true, source: "lib"], ["test/enum_test.exs", "--unlock"]}
   """
   def parse_head(argv, opts // []) when is_list(argv) and is_list(opts) do
     parse(argv, opts, false)