Improve doc of URI.encode

lib/elixir/lib/uri.ex

@@ -367,21 +367,27 @@ defmodule URI do
  @doc """
  Percent-encodes all characters that require escaping in `string`.
 
- By default, this function is meant to escape the whole URI, and
- therefore it will only escape characters which are foreign in
- all parts of a URI. Reserved characters (such as `:` and `/`)
- or unreserved (such as letters and numbers) are not escaped.
-
- Because different components of a URI require different escaping
- rules, this function also accepts a `predicate` function as an optional
- argument. If passed, this function will be called with each byte
- in `string` as its argument and should return a truthy value (anything other
- than `false` or `nil`) if the given byte should be left as is, or
- return a falsy value (`false` or `nil`) if the character should be
- escaped. Defaults to `URI.char_unescaped?/1`.
-
- See `encode_www_form/1` if you are interested in escaping reserved
- characters too.
+ The optional `predicate` argument specifies a function used to detect whether
+ a byte in the `string` should be escaped:
+
+ * if the function returns a truthy value, the byte should be kept as-is.
+ * if the function returns a falsy value, the byte should be escaped.
+
+ The `predicate` argument can use some built-in functions:
+
+ * `URI.char_unescaped?/1` (default) - reserved characters (such as `:`
+ and `/`) or unreserved (such as letters and numbers) are kept as-is.
+ It's typically used to encode the whole URI.
+ * `URI.char_unreserved?/1` - unreserved characters (such as letters and
+ numbers) are kept as-is. It's typically used to encode components in
+ a URI, such as query or fragment.
+ * `URI.char_reserved?/1` - Reserved characters (such as `:` and `/`) are
+ kept as-is.
+
+ And, you can also use custom functions.
+
+ See `encode_www_form/1` if you are interested in encoding `string` as
+ "x-www-form-urlencoded".
 
  ## Examples