Merge pull request #13013 from JuliaLang/jcb/13002

Print the value's type help for undocumented bindings

base/docs/Docs.jl

@@ -95,9 +95,82 @@ function doc(obj)
     end
 end
 
+function write_lambda_signature(io::IO, lam::LambdaStaticData)
+    ex = Base.uncompressed_ast(lam)
+    write(io, '(')
+    nargs = length(ex.args[1])
+    for (i,arg) in enumerate(ex.args[1])
+        argname, argtype = arg.args
+        if argtype === :Any || argtype === :ANY
+            write(io, argname)
+        elseif isa(argtype,Expr) && argtype.head === :... &&
+               (argtype.args[end] === :Any || argtype.args[end] === :ANY)
+            write(io, argname, "...")
+        else
+            write(io, argname, "::", argtype)
+        end
+        i < nargs && write(io, ',')
+    end
+    write(io, ')')
+    return io
+end
+
+function macrosummary(name::Symbol, func::Function)
+    if !isdefined(func,:code) || func.code == nothing
+        return Markdown.parse("\n")
+    end
+    io  = IOBuffer()
+    write(io, "```julia\n")
+    write(io, name)
+    write_lambda_signature(io, func.code)
+    write(io, "\n```")
+    return Markdown.parse(takebuf_string(io))
+end
+
+function functionsummary(func::Function)
+    io  = IOBuffer()
+    write(io, "```julia\n")
+    if isgeneric(func)
+        print(io, methods(func))
+    else
+        if isdefined(func,:code) && func.code !== nothing
+            write_lambda_signature(io, func.code)
+            write(io, " -> ...")
+        end
+    end
+    write(io, "\n```")
+    return Markdown.parse(takebuf_string(io))
+end
+
 function doc(b::Binding)
     d = invoke(doc, Tuple{Any}, b)
-    d == nothing ? doc(getfield(b.mod, b.var)) : d
+    if d === nothing
+        v = getfield(b.mod,b.var)
+        d = doc(v)
+        if d === nothing
+            if isa(v,Function)
+                d = catdoc(Markdown.parse("""
+                No documentation found.
+
+                `$(b.mod === Main ? b.var : join((b.mod, b.var),'.'))` is $(isgeneric(v) ? "a generic" : "an anonymous") `Function`.
+                """), functionsummary(v))
+            elseif startswith(string(b.var),'@')
+                # check to see if the binding var is a macro
+                d = catdoc(Markdown.parse("""
+                No documentation found.
+
+                """), macrosummary(b.var, v))
+            else
+                T = typeof(v)
+                d = catdoc(Markdown.parse("""
+                No documentation found.
+
+                `$(b.mod === Main ? b.var : join((b.mod, b.var),'.'))` is of type `$T`:
+                """), typesummary(typeof(v)))
+            end
+        end
+    end
+    return d
 end
 
 # Function / Method support
@@ -154,7 +227,7 @@ type_morespecific(a::Type, b::Type) =
 # handles the :(function foo(x...); ...; end) form
 function doc!(f::Function, sig::ANY, data, source)
     fd = get!(meta(), f, FuncDoc())
-    isa(fd, FuncDoc) || error("Can't document a method when the function already has metadata")
+    isa(fd, FuncDoc) || error("can not document a method when the function already has metadata")
     haskey(fd.meta, sig) || push!(fd.order, sig)
     sort!(fd.order, lt=type_morespecific)
     fd.meta[sig] = data
@@ -232,45 +305,54 @@ function doc!(t::DataType, data, fields)
     td.fields = fields
 end
 
-function doc!(f::DataType, sig::ANY, data, source)
-    td = get!(meta(), f, TypeDoc())
-    isa(td, TypeDoc) || error("Can't document a method when the type already has metadata")
+function doc!(T::DataType, sig::ANY, data, source)
+    td = get!(meta(), T, TypeDoc())
+    if !isa(td, TypeDoc)
+        error("can not document a method when the type already has metadata")
+    end
     !haskey(td.meta, sig) && push!(td.order, sig)
     td.meta[sig] = data
 end
 
-function doc(f::DataType)
+function doc(T::DataType)
     docs = []
     for mod in modules
-        if haskey(meta(mod), f)
-            fd = meta(mod)[f]
-            if isa(fd, TypeDoc)
-                length(docs) == 0 && fd.main !== nothing && push!(docs, fd.main)
-                for m in fd.order
-                    push!(docs, fd.meta[m])
+        if haskey(meta(mod), T)
+            Td = meta(mod)[T]
+            if isa(Td, TypeDoc)
+                if length(docs) == 0 && Td.main !== nothing
+                    push!(docs, Td.main)
+                end
+                for m in Td.order
+                    push!(docs, Td.meta[m])
                 end
             elseif length(docs) == 0
-                return fd
+                return Td
             end
         end
     end
-    isempty(docs) ? typesummary(f) : catdoc(docs...)
+    if isempty(docs)
+        catdoc(Markdown.parse("""
+        No documentation found.
+
+        """), typesummary(T))
+    else
+        catdoc(docs...)
+    end
 end
 
-function typesummary(f::DataType)
+function typesummary(T::DataType)
     parts = [
     """
-    No documentation found.
-
     **Summary:**
     ```julia
-    $(f.abstract ? "abstract" : f.mutable ? "type" : "immutable") $f <: $(super(f))
+    $(T.abstract ? "abstract" : T.mutable ? "type" : "immutable") $T <: $(super(T))
     ```
     """
     ]
-    if !isempty(fieldnames(f))
-        pad    = maximum([length(string(f)) for f in fieldnames(f)])
-        fields = ["$(rpad(f, pad)) :: $(t)" for (f, t) in zip(fieldnames(f), f.types)]
+    if !isempty(fieldnames(T))
+        pad    = maximum([length(string(f)) for f in fieldnames(T)])
+        fields = ["$(rpad(f, pad)) :: $(t)" for (f,t) in zip(fieldnames(T), T.types)]
         push!(parts,
         """
         **Fields:**
@@ -279,16 +361,16 @@ function typesummary(f::DataType)
         ```
         """)
     end
-    if !isempty(subtypes(f))
+    if !isempty(subtypes(T))
         push!(parts,
         """
         **Subtypes:**
         ```julia
-        $(join(subtypes(f), "\n"))
+        $(join(subtypes(T),'\n'))
         ```
         """)
     end
-    Markdown.parse(join(parts, "\n"))
+    Markdown.parse(join(parts,'\n'))
 end
 
 isfield(x) = isexpr(x, :.) &&
@@ -419,7 +501,7 @@ function docm(meta, def, define = true)
     isexpr(def′, :function)    ? namedoc(meta, def, namify(def′)) :
     isexpr(def′, :call)        ? funcdoc(meta, nothing, def′) :
     isexpr(def′, :type)        ? typedoc(meta, def, def′) :
-    isexpr(def′, :macro)       ?  vardoc(meta, def, symbol("@", namify(def′))) :
+    isexpr(def′, :macro)       ?  vardoc(meta, def, symbol('@',namify(def′))) :
     isexpr(def′, :abstract)    ? namedoc(meta, def, namify(def′)) :
     isexpr(def′, :bitstype)    ? namedoc(meta, def, def′.args[2]) :
     isexpr(def′, :typealias)   ?  vardoc(meta, def, namify(def′)) :
@@ -428,7 +510,7 @@ function docm(meta, def, define = true)
                  :global)      ?  vardoc(meta, def, namify(def′)) :
     isvar(def′)                ? objdoc(meta, def′) :
     isexpr(def′, :tuple)       ? multidoc(meta, def′.args) :
-    isa(def′, Expr)            ? error("Invalid doc expression $def′") :
+    isa(def′, Expr)            ? error("invalid doc expression $def′") :
     objdoc(meta, def′)
 end
 

test/docs.jl

@@ -116,6 +116,13 @@ import .Inner.@m
 "Inner.@m"
 :@m
 
+type Foo
+    x
+end
+
+# value with no docs
+const val = Foo(1.0)
+
 end
 
 import Base.Docs: meta
@@ -213,6 +220,12 @@ let fields = meta(DocsTest)[DocsTest.FieldDocs].fields
     @test haskey(fields, :two) && fields[:two] == doc"two"
 end
 
+# test that when no docs exist, they fallback to
+# the docs for the typeof(value)
+let d1 = @doc(DocsTest.val)
+    @test d1 !== nothing
+end
+
 # Issue #12700.
 @test @doc(DocsTest.@m) == doc"Inner.@m"
 
@@ -227,7 +240,11 @@ end
 
 @doc "This should document @m1... since its the result of expansion" @m2_11993
 @test (@doc @m1_11993) !== nothing
-@test (@doc @m2_11993) === nothing
+let d = (@doc @m2_11993)
+    io = IOBuffer()
+    writemime(io, MIME"text/markdown"(), d)
+    @test startswith(takebuf_string(io),"No documentation found")
+end
 
 @doc "Now @m2... should be documented" :@m2_11993
 @test (@doc @m2_11993) !== nothing
@@ -315,9 +332,15 @@ immutable D <: B
     three::Float64
 end
 
+f = () -> nothing
+
+undocumented() = 1
+undocumented(x) = 2
+undocumented(x,y) = 3
+
 end
 
-@test @doc(Undocumented.A) == doc"""
+@test docstrings_equal(@doc(Undocumented.A), doc"""
 No documentation found.
 
 **Summary:**
@@ -330,9 +353,9 @@ abstract Undocumented.A <: Any
 Undocumented.B
 Undocumented.C
 ```
-"""
+""")
 
-@test @doc(Undocumented.B) == doc"""
+@test docstrings_equal(@doc(Undocumented.B), doc"""
 No documentation found.
 
 **Summary:**
@@ -344,18 +367,18 @@ abstract Undocumented.B <: Undocumented.A
 ```julia
 Undocumented.D
 ```
-"""
+""")
 
-@test @doc(Undocumented.C) == doc"""
+@test docstrings_equal(@doc(Undocumented.C), doc"""
 No documentation found.
 
 **Summary:**
 ```julia
 type Undocumented.C <: Undocumented.A
 ```
-"""
+""")
 
-@test @doc(Undocumented.D) == doc"""
+@test docstrings_equal(@doc(Undocumented.D), doc"""
 No documentation found.
 
 **Summary:**
@@ -369,7 +392,28 @@ one   :: Any
 two   :: UTF8String
 three :: Float64
 ```
-"""
+""")
+
+let d = @doc Undocumented.f
+    io = IOBuffer()
+    writemime(io, MIME"text/markdown"(), d)
+    @test startswith(takebuf_string(io),"""
+    No documentation found.
+
+    `Undocumented.f` is an anonymous `Function`.
+    """)
+end
+
+let d = @doc Undocumented.undocumented
+    io = IOBuffer()
+    writemime(io, MIME"text/markdown"(), d)
+    @test startswith(takebuf_string(io), """
+    No documentation found.
+
+    `Undocumented.undocumented` is a generic `Function`.
+    """)
+end
+
 
 # Bindings.