implement binding docs

JuliaLang · Jul 10, 2015 · 5380268 · 5380268
1 parent 033077c
commit 5380268
Show file tree

Hide file tree

Showing 2 changed files with 44 additions and 11 deletions.
diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
@@ -221,6 +221,13 @@ end
 
 const keywords = Dict{Symbol,Any}()
 
+# Bindings
+
+function doc(b::Meta.Binding)
+    d = invoke(doc, (Any,), b)
+    d != nothing ? d : doc(b[])
+end
+
 # Usage macros
 
 isexpr(x::Expr) = true
@@ -272,23 +279,40 @@ function objdoc(meta, def)
     end
 end
 
+function vardoc(meta, def, name)
+    quote
+        @init
+        f = $(esc(def))
+        # @var isn't found – bug?
+        doc!(Meta.@var($(esc(name))), $(mdify(meta)))
+        f
+    end
+end
+
 function docm(meta, def)
     @match def begin
-        :(@m_) -> return objdoc(meta, m)
-          m_"" -> return objdoc(meta, m)
+        :(@m_)      -> return objdoc(meta, m)
+          m_""      -> return objdoc(meta, m)
+        (@var x_)   -> vardoc(meta, def, x)
     end
     def = macroexpand(def)
     @match def begin
         (f_(__) = _)          -> funcdoc(meta, def)
         function f_(__) _ end -> funcdoc(meta, def)
         function f_ end       ->  objdoc(meta, def)
         macro m_(__) _ end    -> namedoc(meta, def, symbol("@", m))
+
         type T_ _ end         -> typedoc(meta, def, namify(T))
         immutable T_ _ end    -> typedoc(meta, def, namify(T))
         (abstract T_)         -> namedoc(meta, def, namify(T))
         (bitstype _ T_)       -> namedoc(meta, def, namify(T))
         (typealias T_ _)      ->  objdoc(meta, def)
+
         module M_ _ end       -> namedoc(meta, def, M)
+
+        (x_ = _)              ->  vardoc(meta, def, namify(x))
+        (const x_ = _)        ->  vardoc(meta, def, namify(x))
+
         _                     -> !isa(def, Expr) ? objdoc(meta, def) :
                                      error("Unsupported @doc syntax $def")
     end
@@ -299,8 +323,15 @@ function docm(ex)
     @match ex begin
         (meta_ -> def_) -> docm(meta, def)
         f_(__)          -> :(doc($(esc(f))), @which $(esc(ex)))
-        (@m_)           -> :(doc($(esc(m))))
-        _               -> :(doc($(esc(ex))))
+
+        (@m_)           -> :(doc(Meta.@var($(esc(ex)))))
+        (_.@m_)         -> :(doc(Meta.@var($(esc(ex)))))
+        (_._)           -> :(doc(Meta.@var($(esc(ex)))))
+        (@var x_)       -> :(doc(Meta.@var($(esc(x)))))
+
+        _               -> isa(ex, Symbol) ?
+                             :(doc(Meta.@var($(esc(ex))))) :
+                             :(doc($(esc(ex))))
     end
 end
 

diff --git a/test/docs.jl b/test/docs.jl
@@ -1,5 +1,7 @@
 # This file is a part of Julia. License is MIT: http://julialang.org/license
 
+using Base.Meta
+
 @doc "Doc abstract type" ->
 abstract C74685 <: AbstractArray
 @test stringmime("text/plain", Docs.doc(C74685))=="Doc abstract type\n"
@@ -135,11 +137,11 @@ typealias TA Union(T, IT)
 "@mac"
 macro mac() end
 
-# "G"
-# G = :G
-#
-# "K"
-# const K = :K
+"G"
+G = :G
+
+"K"
+const K = :K
 
 end
 
@@ -192,8 +194,8 @@ let mac = getfield(DocsTest, symbol("@mac"))
     @test funcdoc.main == doc"@mac"
 end
 
-# @test meta(DocsTest)[:G] == doc"G"
-# @test meta(DocsTest)[:K] == doc"K"
+@test meta(DocsTest)[@var(DocsTest.G)] == doc"G"
+@test meta(DocsTest)[@var(DocsTest.K)] == doc"K"
 
 # issue 11993
 # Check if we are documenting the expansion of the macro