   defmacro super(args)
 
   @doc """
-  Matches the given expression against the match clauses.
+  Matches the given expression against the given clauses.
 
   ## Examples
 
       case thing do
         { :selector, i, value } when is_integer(i) ->
           value
-        value -> value
-      end
-
-  In the example above, we compare `thing` with each given match
-  clause and evaluate the expression corresponding to the first clause
+        value ->
+          value
+      end
+
+  In the example above, we match `thing` against each clause "head"
+  and execute the clause "body" corresponding to the first clause
   that matches. If no clause matches, an error is raised.
 
-  Since Elixir variables can be assigned more than once, variables
-  in a match clause will always be assigned instead of matching with
-  its previous values. For example:
-
-      i = 1
-      case 10 do
-        i -> i * 2
-      end
-
-  The example above will return 20, because `i` is assigned to 10
-  and then multiplied by 2. If you desire to match the value of `i`
-  against the given condition, you need to use the `^` operator:
-
-      i = 1
-      case 10 do
-        ^i -> i * 2
-      end
-
-  The example above will actually fail because 10 does not match 1.
+  ## Variables handling
+
+  Notice that variables bound in a clause "head" do not leak to the
+  outer context:
+
+      case data do
+        { :ok, value } -> value
+        :error -> nil
+      end
+
+      value #=> unbound variable value
+
+  However, variables explicitly bound in the clause "body" are
+  accessible from the outer context:
+
+      value = 7
+
+      case lucky? do
+        false -> value = 13
+        true  -> true
+      end
+
+      value #=> 7 or 13
+
+  In the example above, value is going to be `7` or `13` depending on
+  the value of `lucky?`. In case `value` has no previous value before
+  case, clauses that do not explicitly bind a value have the variable
+  bound to nil.
   """
   defmacro case(condition, blocks)
 
   @doc """
-  Evaluate the given expressions and catch any error, exit
+  Evaluate the given expressions and handle any error, exit
   or throw that may have happened.
 
   ## Examples

  """
  defmacro __DIR__

  @doc %S"""
  Gets the representation of any expression.


        _, _ -> :failed
      end

      x #=> unbound variable `x`

  In the example above, `x` cannot be accessed since it was defined
  inside the `try` clause. A common practice to address this issue
