added @macroexpand

base/expr.jl

@@ -65,6 +65,32 @@ macroexpand(x::ANY) = ccall(:jl_macroexpand, Any, (Any,), x)
     @macroexpand
 
 Return equivalent expression with all macros removed (expanded).
+
+There is a subtle difference between `@macroexpand` and `macroexpand` in that expansion takes place in
+different contexts. This is best seen in the following example:
+
+```jldoctest
+julia> module M
+           macro m()
+               1
+           end
+           function f()
+              (@macroexpand(@m), macroexpand(:(@m)))
+           end
+       end
+M
+
+julia> macro m()
+          2
+       end
+@m (macro with 1 method)
+
+julia> M.f()
+(1,2)
+```
+With @macroexpand the expression expands where @macroexpand appears in the code (module M).
+With macroexpand the expressions expands in the current module where the code was finally called.
+Note that when calling macroexpand or @macroexpand directly from the REPL, both of these contexts coincide, hence there is no difference.
 """
 macro macroexpand(code)
     code_expanded = macroexpand(code)

doc/stdlib/base.rst

@@ -1523,6 +1523,30 @@ Internals
 
    Return equivalent expression with all macros removed (expanded).
 
+   There is a subtle difference between ``@macroexpand`` and ``macroexpand`` in that expansion takes place in different contexts. This is best seen in the following example:
+
+   .. doctest::
+
+       julia> module M
+                  macro m()
+                      1
+                  end
+                  function f()
+                     (@macroexpand(@m), macroexpand(:(@m)))
+                  end
+              end
+       M
+
+       julia> macro m()
+                 2
+              end
+       @m (macro with 1 method)
+
+       julia> M.f()
+       (1,2)
+
+   With @macroexpand the expression expands where @macroexpand appears in the code (module M). With macroexpand the expressions expands in the current module where the code was finally called. Note that when calling macroexpand or @macroexpand directly from the REPL, both of these contexts coincide, hence there is no difference.
+
 .. function:: expand(x)
 
    .. Docstring generated from Julia source

test/replutil.jl

@@ -447,3 +447,22 @@ let d = Dict(1 => 2, 3 => 45)
         @test contains(replace(result, " ", ""), string(el))
     end
 end
+
+
+# @macroexpand tests
+macro seven_dollar(ex)
+    # simonbyrne example 18240
+    isa(ex,Expr) && ex.head == :$ ? 7 : ex
+end
+
+let
+    @test (@macroexpand @macroexpand x) == macroexpand(:(@macroexpand x))
+    @test (@macroexpand  :(1+$y) ) == macroexpand(:( :(1+ $y)))
+    @test (@macroexpand @fastmath 1+2    ) == :(Base.FastMath.add_fast(1,2))
+    @test (@macroexpand @fastmath +      ) == :(Base.FastMath.add_fast)
+    @test (@macroexpand @fastmath min(1) ) == :(Base.FastMath.min_fast(1))
+    @test (@macroexpand @doc "" f() = @x) == Expr(:error, UndefVarError(Symbol("@x")))
+    @test (@macroexpand @seven_dollar $bar) == 7
+    x = 2
+    @test (@macroexpand @seven_dollar 1+$x) == :(1 + $(Expr(:$, :x)))
+end