   Low-level function that parses one option.
 
   It accepts the same options as `parse/2` and `parse_head/2`
-  as both functions are built on top of next. This function
+  as both functions are built on top of this function. This function
   may return:
 
     * `{:ok, key, value, rest}` - the option `key` with `value` was
       successfully parsed
 
     * `{:invalid, key, value, rest}` - the option `key` is invalid with `value`
-      (returned when the switch type does not match the one given via the
-      command line)
+      (returned when the value cannot be parsed according to the switch type)
 
     * `{:undefined, key, value, rest}` - the option `key` is undefined
       (returned in strict mode when the switch is unknown)
 
-    * `{:error, rest}` - there are no switches at the top of the given argv
+    * `{:error, rest}` - there are no switches at the head of the given `argv`
+
   """
 
   @spec next(argv, options) ::

      iex> OptionParser.parse(["--source-path", "lib", "test/enum_test.exs", "--verbose"])
      {[source_path: "lib", verbose: true], ["test/enum_test.exs"], []}

  By default, Elixir will try to automatically parse all switches.
  Switches followed by a value will be assigned the value, as a string.
  Switches without an argument, like `--debug` will automatically
  be set to `true`.

  Note: Elixir also converts the switches to underscore atoms, so
  `--source-path` becomes `:source_path`, to better suit Elixir
  conventions. This means that option names on the command line cannot
  contain underscores; such options will be put in the invalid options
  list.

  ## Switch Definitions

  Often it is better to explicitly list the known
  switches and their formats. The switches can be specified via two
  alternative options:

    * `:switches` - defines some switches. An attempt is still made to parse
      switches that do not appear in the list.

    * `:strict` - the switches are strict. Any switch that is not specified
      in the list is returned in the invalid options list.

  Note that you should only supply the `:switches` or `:strict` option.
  If you supply both, an error will be raised.

  ### Types

  Option parser switches may take 0 or 1 argument.

  The following switches take no argument:

    * `:boolean` - sets the value to true when given
    * `:count`   - counts the number of times the switch is given

  The following switches take 1 argument:

    * `:integer` - parses the upcoming value as an integer.
    * `:float`   - parses the upcoming value as a float.
    * `:string`  - parses the upcoming value as a string.

  If a switch can't be parsed, it is returned in the invalid
  options list.

  ### Modifiers

  Switches can be specified with modifiers, which change how
  they behave. The following modifiers are supported:

    * `:keep` - keeps duplicated items instead of overriding them.
      Works with all types except `:count`.

  Note: if you want to use `:keep` with a non-string type, use a list, e.g.
  `[foo: [:integer, :keep]]`.

  ### Examples

  Here are some examples of option parser working with different types
  and modifiers:

      iex> OptionParser.parse(["--unlock", "path/to/file"], strict: [unlock: :boolean])
      {[unlock: true], ["path/to/file"], []}

  @spec parse_head!(argv, options) :: {parsed, argv, errors} | no_return
  def parse_head!(argv, opts \\ []) when is_list(argv) and is_list(opts) do
    case parse_head(argv, opts) do
      {parsed, args, []} -> {parsed, args}
      {_, _, errors} -> raise ParseError, format_errors(errors, opts)
    end
  end
