From 188ab3fd03c16d24412466d6b3d50b0f0980dad8 Mon Sep 17 00:00:00 2001
From: c4710n <c4710n@users.noreply.github.com>
Date: Wed, 16 Oct 2024 15:34:10 +0800
Subject: [PATCH] Improve doc of URI.encode

---
 lib/elixir/lib/uri.ex | 36 +++++++++++++++++++++---------------
 1 file changed, 21 insertions(+), 15 deletions(-)

diff --git a/lib/elixir/lib/uri.ex b/lib/elixir/lib/uri.ex
index 53bd919cf42..c05d8c94ba9 100644
--- a/lib/elixir/lib/uri.ex
+++ b/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