   end
 
   @doc ~S"""
-  Unescapes the given chars according to the map given.
-
-  Check `unescape_string/1` if you want to use the same map
+  Unescapes characters in a string according to the given mapping.
+
+  Check `unescape_string/1` if you want to use the same mapping
   as Elixir single- and double-quoted strings.
 
-  ## Map
-
-  The map must be a function. The function receives an integer
-  representing the code point of the character it wants to unescape.
+  ## Mapping function
+
+  The mapping function receives an integer representing the code point
+  of the character it wants to unescape. There are also the special atoms
+  `:newline`, `:unicode`, and `:hex`, which control newline, unicode,
+  and escaping respectively.
+
   Here is the default mapping function implemented by Elixir:
 
       def unescape_map(:newline), do: true

  If the `unescape_map/1` function returns `false`, the char is
  not escaped and the backslash is kept in the string.

  Newlines, Unicode, and hexadecimals code points will be escaped if
  the map returns `true` respectively for `:newline`, `:unicode`, and
  `:hex`.

  ## Examples

  Using the `unescape_map/1` function defined above is easy:

  `\uNNNN` escapes.

  This function is commonly used on sigil implementations
  (like `~r`, `~s` and others), which receive a raw, unescaped
  string, and it can be used anywhere that needs to mimic how
  Elixir parses strings.

  ## Examples

