Mention Macro.escape/1 in quote docs

1 files changed, 31 insertions, 13 deletions

diff --git a/lib/elixir/lib/kernel/special_forms.ex b/lib/elixir/lib/kernel/special_forms.ex
index fceb8cc0a..6c64648ae 100644
--- a/lib/elixir/lib/kernel/special_forms.ex
+++ b/lib/elixir/lib/kernel/special_forms.ex
@@ -778,7 +778,7 @@ defmodule Kernel.SpecialForms do
       ...> end
       {:sum, [], [1, 2, 3]}
 
-  ## Explanation
+  ## Elixir's AST (abstract syntax tree)
 
   Any Elixir code can be represented using Elixir data structures.
   The building block of Elixir macros is a tuple with three elements,
@@ -798,6 +798,20 @@ defmodule Kernel.SpecialForms do
       function call. The third argument may be an atom, which is
       usually a variable (or a local call).
 
+  Besides the tuple described above, Elixir has a few literals that
+  are also part of its AST. Those literals return themselves when
+  quoted. They are:
+
+      :sum         #=> Atoms
+      1            #=> Integers
+      2.0          #=> Floats
+      [1, 2]       #=> Lists
+      "strings"    #=> Strings
+      {key, value} #=> Tuples with two elements
+
+  If you would like to introduce any other value into an AST, you need
+  to make sure those values are escaped before via `Macro.escape/1`.
+
   ## Options
 
     * `:unquote` - when `false`, disables unquoting. This means any `unquote`
@@ -829,18 +843,6 @@ defmodule Kernel.SpecialForms do
     * `:bind_quoted` - passes a binding to the macro. Whenever a binding is
       given, `unquote/1` is automatically disabled.
 
-  ## Quote literals
-
-  Besides the tuple described above, Elixir has a few literals that
-  when quoted return themselves. They are:
-
-      :sum         #=> Atoms
-      1            #=> Integers
-      2.0          #=> Floats
-      [1, 2]       #=> Lists
-      "strings"    #=> Strings
-      {key, value} #=> Tuples with two elements
-
   ## Quote and macros
 
   `quote/2` is commonly used with macros for code generation. As an exercise,
@@ -1263,6 +1265,11 @@ defmodule Kernel.SpecialForms do
   @doc """
   Unquotes the given expression inside a quoted expression.
 
+  This function expects a valid Elixir AST, also known as
+  quoted expression, as argument. If you would like to `unquote`
+  any value, such as a map or a four-element tuple, you should
+  call `Macro.escape/1` before unquoting.
+
   ## Examples
 
   Imagine the situation you have a quoted expression and
@@ -1293,6 +1300,17 @@ defmodule Kernel.SpecialForms do
       ...> end
       {:sum, [], [1, 13, 3]}
 
+  Note, however, if you want to unquote a value into a AST,
+  you need to call `Macro.escape/1` before:
+
+      iex> value = %{foo: :bar}
+      iex> quote do
+      ...>   process_map(unquote(Macro.escape(value)))
+      ...> end
+      {:process_map, [], [{:%{}, [], [foo: :bar]}]}
+
+  If you forget to escape it, Elixir will raise an error
+  when compiling the code.
   """
   defmacro unquote(:unquote)(expr), do: error!([expr])