     * `: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.
-
-  For each switch, the following types are supported:
-
-    * `:boolean` - marks the given switch as a boolean. Boolean switches
-      never consume the following value unless it is `true` or
-      `false`.
-    * `:count`   - parses the switch as a counter, ignores `:keep`.
-    * `:integer` - parses the switch as an integer.
-    * `:float`   - parses the switch as a float.
-    * `:string`  - returns the switch as a string.
-
-  If a switch can't be parsed, it is returned in the invalid options list.
-
-  The following extra "types" are supported:
-
-    * `:keep` - keeps duplicated items in the list instead of overriding them.
+  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:
+  ### 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"], []}

    {value, kinds, t}
  end

  defp value_in_tail?(["-" | _]),         do: true
  defp value_in_tail?(["- " <> _ | _]),   do: true
  defp value_in_tail?(["-" <> arg | _]),  do: negative_number?("-" <> arg)
  defp value_in_tail?([]),              do: false
  defp value_in_tail?(_),               do: true

  defp split_option(option) do
    case :binary.split(option, "=") do

    end
  end

  defp tag_option("-no-" <> option, switches, _aliases) do
    cond do
      (negated = get_option(option)) && :boolean in List.wrap(switches[negated]) ->
        {:negated, negated}
      option = get_option("no-" <> option) ->
        {:default, option}
      true ->
        :unknown
    end
  end

  defp tag_option("-" <> option, _switches, _aliases) do
    if option = get_option(option) do
      {:default, option}
    else
      :unknown
    end
  end

  defp tag_option(option, _switches, aliases) when is_binary(option) do
