From 292a34da94c2bc489eb69e3f400444ae1fc90595 Mon Sep 17 00:00:00 2001
From: Michael Hatherly <michaelhatherly@gmail.com>
Date: Mon, 29 Feb 2016 23:10:48 +0200
Subject: [PATCH] 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 | 16 +++++++++++++---
 test/docs.jl      | 29 +++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
index 88773ad2aca0b..dcdd78a349482 100644
--- a/base/docs/Docs.jl
+++ b/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)
diff --git a/test/docs.jl b/test/docs.jl
index d5e65e70480dd..deeb9e008969e 100644
--- a/test/docs.jl
+++ b/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.