Better support for documenting expressions with macros. Fix #11993

JuliaLang · Jul 4, 2015 · 29a8eea · MichaelHatherly · Jul 4, 2015 · 29a8eea
1 parent 1368cae
commit 29a8eea
Show file tree

Hide file tree

Showing 2 changed files with 6 additions and 8 deletions.
diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
@@ -283,21 +283,21 @@ end
 fexpr(ex) = isexpr(ex, :function, :(=)) && isexpr(ex.args[1], :call)
 
 function docm(meta, def)
+    isexpr(def, :macrocall) && (def = macroexpand(def))
     def′ = unblock(def)
     isexpr(def′, :macro) && return namedoc(meta, def, symbol("@", namify(def′)))
     isexpr(def′, :type, :bitstype) && return typedoc(meta, def, namify(def′.args[2]))
     isexpr(def′, :abstract) && return namedoc(meta, def, namify(def′))
     isexpr(def′, :module) && return namedoc(meta, def, def′.args[2])
     fexpr(def′) && return funcdoc(meta, def)
-    isexpr(def′, :macrocall) && (def = namify(def′))
     return objdoc(meta, def)
 end
 
 function docm(ex)
+    isexpr(ex, :macrocall) && (ex = macroexpand(ex))
     isa(ex,Symbol) && haskey(keywords, ex) && return keywords[ex]
     isexpr(ex, :->) && return docm(ex.args...)
     isexpr(ex, :call) && return :(doc($(esc(ex.args[1])), @which $(esc(ex))))
-    isexpr(ex, :macrocall) && (ex = namify(ex))
     :(doc($(esc(ex))))
 end
 
@@ -326,7 +326,7 @@ Please see docs for the `@doc` macro for more info.
 """
 Docs
 
-"""
+@eval @doc """
 # Documentation
 
 Functions, methods and types can be documented by placing a string before the
@@ -363,8 +363,7 @@ Placing documentation before a method definition (e.g. `function foo()
 documented, as opposed to the whole function. Method docs are
 concatenated together in the order they were defined to provide docs
 for the function.
-"""
-@doc
+""" $(symbol("@doc"))
 
 "`doc(obj)`: Get the doc metadata for `obj`."
 doc

diff --git a/base/docs/basedocs.jl b/base/docs/basedocs.jl
@@ -286,7 +286,7 @@ keywords[:immutable] = doc"""
   See `type` and the manual for more information.
   """
 
-"""
+@eval @doc """
 Executes an expression, printing the time it took to
 execute and the total number of bytes its execution caused to be
 allocated. Returns the value of the expression. For example:
@@ -295,8 +295,7 @@ allocated. Returns the value of the expression. For example:
       sleep(1)
       2+2
     end
-"""
-@time
+""" $(symbol("@time"))
 
 doc"""
 Construct a regex, such as `r"^[a-z]*$"`. The regex also accepts