Improve docs and error messages

Author: José Valim

lib/elixir/lib/kernel/special_forms.ex

@@ -484,8 +484,8 @@ defmodule Kernel.SpecialForms do
   """
   defmacro __DIR__
 
-  @doc """
-  Allows you to get the representation of any expression.
+  @doc %S"""
+  Gets the representation of any expression.
 
   ## Examples
 
@@ -522,7 +522,7 @@ defmodule Kernel.SpecialForms do
   * `:bind_quoted` - Passes a binding to the macro. Whenever a binding is given,
                     `unquote` is automatically disabled;
 
-  ## Macro literals
+  ## Quote literals
 
   Besides the tuple described above, Elixir has a few literals that
   when quoted return themselves. They are:
@@ -531,43 +531,111 @@ defmodule Kernel.SpecialForms do
       1            #=> Integers
       2.0          #=> Floats
       [1, 2]       #=> Lists
-      "binaries"   #=> Binaries
+      "strings"    #=> Strings
       {key, value} #=> Tuple with two elements
 
-  ## Hygiene and context
+  ## Quote and macros
+
+  `quote` is commonly used with macros for code generation. As an exercise,
+  let's define a macro that multiplies a number by itself (squared). Note
+  there is no reason to define such as a macro (and it would actually be
+  seen as a bad practice), but it is simple enough that allows us to focus
+  on the important aspects of quotes and macros:
+
+      defmodule Math do
+        defmacro squared(x) do
+          quote do
+            unquote(x) * unquote(x)
+          end
+        end
+      end
+
+  We can invoke it as:
+
+      import Math
+      IO.puts "Got #{squared(5)}"
+
+  At first, there is nothing in this example that actually reveals it is a
+  macro. But what is happening is that, at compilation time, `squared(5)`
+  becomes `5 * 5`. We can see this behaviour in practice though
+  because our macro actually has a bug:
+
+      import Math
+      my_number = fn ->
+        IO.puts "Returning 5"
+        5
+      end
+      IO.puts "Got #{squared(my_number.())}"
+
+  The example above will print:
+
+      Returning 5
+      Returning 5
+      25
+
+  Notice how "Returning 5" was printed twice, instead of just once. This is
+  because a macro receives an expression and not a value (which is what we
+  would expect in a regular function). This means that:
 
-  Elixir macros are hygienic by means of deferred resolution.
-  This means variables, aliases and imports defined inside the
-  quoted refer to the context that defined the macro and not
-  the context where the macro is expanded.
+      squared(my_number.())
 
-  For this mechanism to work, every quoted code is attached
-  to a context. Consider the following example:
+  Actually expands to:
 
-      defmodule ContextSample do
-        def hello do
-          quote do: world
+      my_number.() * my_number.()
+
+  Which invokes the function twice, explaining why we get the printed value
+  twice! In the majority of the cases, this is actually unexpected behaviour,
+  and that's why one of the first things you need to keep in mind when it
+  comes to macros is to **not unquote the same value more than once**.
+
+  Let's fix our macro:
+
+      defmodule Math do
+        defmacro squared(x) do
+          quote do
+            x = unquote(x)
+            x * x
+          end
+        end
+      end
+
+  Now invoking `square(my_number.())` as before will print the value just
+  once.
+
+  In fact, this pattern is so common that most of the times you will want
+  to use the `bind_quoted` option with `quote`:
+
+      defmodule Math do
+        defmacro squared(x) do
+          quote bind_quoted: [x: x] do
+            x * x
+          end
         end
       end
 
-      ContextSample.hello
-      #=> {:world,[],ContextSample}
+  `:bind_quoted` will translate to the same example as above. `:bind_quoted`
+  can be used in many cases and is seen as good practice, not only because
+  it helps us from running into common mistakes but also because it allows
+  us to leverage other tools exposed by macros, as unquote fragments discussed
+  in some sections below.
+
+  Before we finish this brief introduction, you will notice that, even though
+  we defined a variable `x` inside our quote:
+
+      quote do
+        x = unquote(x)
+        x * x
+      end
 
-  Notice how the third element of the returned tuple is the
-  module name. This means that the variable is associated to the
-  `ContextSample` module and only code generated by this module
-  will be able to access that particular `world` variable. Not
-  only variables hygiene, but also imports and aliases hygiene
-  are delimited by context.
+  When we call:
 
-  While this means macros from the same module could have
-  conflicting variables, it also allows different quotes from
-  the same module to access them.
+      import Math
+      squared(5)
+      x #=> ** (RuntimeError) undefined function or variable: x
 
-  The context can be disabled or changed by explicitly setting
-  the `context` option. All hygiene mechanisms are based on such
-  context and we are going to explore each of them in the following
-  subsections.
+  We can see that `x` did not leak to the user context. This happens
+  because Elixir macros are hygienic, a topic we will discuss at length
+  in the next sections as well.
 
   ### Hygiene in variables
 
@@ -622,7 +690,7 @@ defmodule Kernel.SpecialForms do
 
       Hygiene.write
       Hygiene.read
-      #=> no variable a
+      #=> ** (RuntimeError) undefined function or variable: a
 
   For such, you can explicitly pass the current module scope as
   argument:
@@ -839,8 +907,8 @@ defmodule Kernel.SpecialForms do
   One solution for this problem is to disable unquoting in the
   macro, however, doing that would make it impossible to inject
   `kv` representation into the tree. That's when the `:bind_quoted`
-  option comes to the rescue. By using `:bind_quoted`, we can
-  automatically disable unquoting while still injecting the
+  option comes to the rescue (again!). By using `:bind_quoted`, we
+  can automatically disable unquoting while still injecting the
   desired variables into the tree:
 
       defmacro defkv(kv) do

lib/mix/lib/mix/project.ex

@@ -54,7 +54,7 @@ defmodule Mix.Project do
         :ok
       { :error, other } when is_binary(other) ->
         raise Mix.Error, message: "Trying to load #{inspect atom} from #{inspect file}" <>
-          " but another project with the same was already defined at #{inspect other}"
+          " but another project with the same name was already defined at #{inspect other}"
     end
   end