Add metadata to markdown returned by at-doc.

This commit saves some of the values computed by `doc` and
`summarise` into the generated `MD` object that is returned.
These valus are the `Binding` and signature searched for, as
well as the vector of `DocStr` objects that match the `Binding`
and signature.

base/docs/Docs.jl

@@ -232,8 +232,13 @@ function doc(binding::Binding, sig::Type = Union)
                 push!(results, group.docs[each])
             end
         end
-        # Get the parsed docs, concatenate, and return the result.
-        Markdown.MD(map(parsedoc, results))
+        # Get parsed docs and concatenate them.
+        md = Markdown.MD(map(parsedoc, results))
+        # Save metadata in the generated markdown.
+        md.meta[:results] = results
+        md.meta[:binding] = binding
+        md.meta[:typesig] = sig
+        return md
     end
 end
 
@@ -276,7 +281,12 @@ function summarise(binding::Binding, sig)
     else
         println(io, "Binding `", binding, "` does not exist.")
     end
-    Markdown.parse(seekstart(io))
+    md = Markdown.parse(seekstart(io))
+    # Save metadata in the generated markdown.
+    md.meta[:results] = DocStr[]
+    md.meta[:binding] = binding
+    md.meta[:typesig] = sig
+    return md
 end
 
 function summarise(io::IO, λ::Function, binding)

test/docs.jl

@@ -630,6 +630,35 @@ let d = @doc Undocumented.undocumented
     """)
 end
 
+# `@doc` "metadata".
+
+let m = @doc(DocsTest).meta
+    @test length(m[:results]) == 1
+    @test m[:results][1] === Docs.meta(DocsTest)[@var(DocsTest)].docs[Union{}]
+    @test m[:binding] == @var(DocsTest)
+    @test m[:typesig] == Union
+end
+
+let m = @doc(DocsTest.f).meta
+    @test length(m[:results]) == 2
+    @test m[:results][1] === Docs.meta(DocsTest)[@var(DocsTest.f)].docs[Tuple{Any}]
+    @test m[:results][2] === Docs.meta(DocsTest)[@var(DocsTest.f)].docs[Tuple{Any, Any}]
+    @test m[:binding] == @var(DocsTest.f)
+    @test m[:typesig] == Union
+end
+
+let m = @doc(DocsTest.f(x)).meta
+    @test length(m[:results]) == 1
+    @test m[:results][1] === Docs.meta(DocsTest)[@var(DocsTest.f)].docs[Tuple{Any}]
+    @test m[:binding] == @var(DocsTest.f)
+    @test m[:typesig] == Tuple{Any}
+end
+
+let m = @doc(Undocumented.f).meta
+    @test isempty(m[:results])
+    @test m[:binding] == @var(Undocumented.f)
+    @test m[:typesig] == Union
+end
 
 # Bindings.