Better support for documenting expressions with macros. Fix #11993

base/docs/Docs.jl

@@ -283,6 +283,9 @@ end
 fexpr(ex) = isexpr(ex, :function, :(=)) && isexpr(ex.args[1], :call)
 
 function docm(meta, def)
+    if isexpr(def, :macrocall) && length(def.args) > 1
+        def = macroexpand(def)
+    end
     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]))
@@ -294,6 +297,9 @@ function docm(meta, def)
 end
 
 function docm(ex)
+    if isexpr(ex, :macrocall) && length(ex.args) > 1
+        ex = macroexpand(ex)
+    end
     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))))
@@ -363,8 +369,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
+""" @doc
 
 "`doc(obj)`: Get the doc metadata for `obj`."
 doc

base/docs/basedocs.jl

@@ -295,8 +295,7 @@ allocated. Returns the value of the expression. For example:
       sleep(1)
       2+2
     end
-"""
-@time
+""" @time
 
 doc"""
 Construct a regex, such as `r"^[a-z]*$"`. The regex also accepts

src/julia-parser.scm

@@ -2076,10 +2076,19 @@
 
 (define (parse-docstring s production)
   (let* ((isstr (eqv? (peek-token s) #\"))
-	 (ex    (production s)))
+	 (ex    (production s))
+         (next  (peek-token s)))
     (if (and (or isstr (any-string-literal? ex))
-	     (not (closing-token? (peek-token s))))
-	`(macrocall (|.| Base (quote @doc)) ,ex ,(production s))
+	     (not (closing-token? next)))
+        (let ((arg (production s)))
+          (if (and (newline? next)
+                   ;; What follows the string literal is a newline and
+                   ;; a single macro call
+                   (pair? arg)
+                   (eq? (car arg) 'macrocall)
+                   (not (pair? (cddr arg))))
+              `(block ,ex ,arg)
+              `(macrocall (|.| Base (quote @doc)) ,ex ,arg)))
 	ex)))
 
 ; --- main entry point ---