   @doc """
   Parses `argv` into a keywords list.
 
-  It returns the parsed values, remaining arguments and the
-  invalid options.
+  It returns a three-element tuple as follows:
+
+     1. parsed switches,
+     2. remaining arguments,
+     3. invalid options.
 
   ## Examples
 

    * `:float`   - parses the switch as a float.
    * `:string`  - returns the switch as a string.

  If a switch can't be parsed or is not specified in the strict case,
  the option is returned in the invalid options list (third element
  of the returned tuple).

  The following extra "types" are supported:

    * `:keep` - keeps duplicated items in the list instead of overriding

  Examples:


      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, the `:strict` option will be ignored.

  For each switch, the following types are supported:

