From ae7ba6af40ea2c7b89edc76338d53aeb604da23a Mon Sep 17 00:00:00 2001
From: Jake Bolewski <jakebolewski@gmail.com>
Date: Wed, 9 Sep 2015 22:17:22 -0400
Subject: [PATCH] special case help output for functions with no docstrings

add some tests
---
 base/docs/Docs.jl | 84 +++++++++++++++++++++++++++++++----------------
 test/docs.jl      | 27 +++++++++++++++
 2 files changed, 83 insertions(+), 28 deletions(-)

diff --git a/base/docs/Docs.jl b/base/docs/Docs.jl
index c9435b6ba0c2e..f248acecdba44 100644
--- a/base/docs/Docs.jl
+++ b/base/docs/Docs.jl
@@ -95,43 +95,71 @@ 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)
-    parts = ["""
-
-    No documentation found.
-    """]
-    if isdefined(func,:code) && func.code != nothing
-        lam = Base.uncompressed_ast(func.code)
-        io  = IOBuffer()
-        write(io, name, '(')
-        nargs = length(lam.args[1])
-        for (i,arg) in enumerate(lam.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, ',')
+    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
-        write(io, ')')
-        push!(parts, string("```julia\n", takebuf_string(io), "\n```"))
     end
-    Markdown.parse(join(parts,'\n'))
+    write(io, "\n```")
+    return Markdown.parse(takebuf_string(io))
 end
 
 function doc(b::Binding)
     d = invoke(doc, Tuple{Any}, b)
-    if d == nothing
+    if d === nothing
         v = getfield(b.mod,b.var)
         d = doc(v)
-        if d == nothing
-            # check to see if the binding var is a macro
-            if startswith(string(b.var),'@')
-                d = macrosummary(b.var, 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("""
diff --git a/test/docs.jl b/test/docs.jl
index 64af508276ff5..8f6d15b189550 100644
--- a/test/docs.jl
+++ b/test/docs.jl
@@ -332,6 +332,12 @@ immutable D <: B
     three::Float64
 end
 
+f = () -> nothing
+
+undocumented() = 1
+undocumented(x) = 2
+undocumented(x,y) = 3
+
 end
 
 @test docstrings_equal(@doc(Undocumented.A), doc"""
@@ -388,6 +394,27 @@ 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.
 
 import Base.Docs: @var, Binding