show multiple docstrings in REPL more clearly (#25651)

* show multiple docstrings in REPL more clearly

this is done by printing a horizontal line after each separate docstring

Author: KristofferC

Diff for: base/docs/Docs.jl

@@ -179,7 +179,7 @@ function formatdoc(d::DocStr)
     for part in d.text
         formatdoc(buffer, d, part)
     end
-    Markdown.parse(seekstart(buffer))
+    Markdown.MD(Any[Markdown.parse(seekstart(buffer))])
 end
 @noinline formatdoc(buffer, d, part) = print(buffer, part)
 

Diff for: base/docs/utils.jl

@@ -94,7 +94,11 @@ end
 
 # REPL help
 
-function helpmode(io::IO, line::AbstractString)
+# This is split into helpmode and _helpmode to easier unittest _helpmode
+helpmode(io::IO, line::AbstractString) = :(Base.Docs.insert_hlines($io, $(Base.Docs._helpmode(io, line))))
+helpmode(line::AbstractString) = helpmode(STDOUT, line)
+
+function _helpmode(io::IO, line::AbstractString)
     line = strip(line)
     expr =
         if haskey(keywords, Symbol(line))
@@ -114,7 +118,21 @@ function helpmode(io::IO, line::AbstractString)
     # so that the resulting expressions are evaluated in the Base.Docs namespace
     :(Base.Docs.@repl $io $expr)
 end
-helpmode(line::AbstractString) = helpmode(STDOUT, line)
+_helpmode(line::AbstractString) = _helpmode(STDOUT, line)
+
+# Print vertical lines along each docstring if there are multiple docs
+function insert_hlines(io::IO, docs)
+    if !isa(docs, Markdown.MD) || !haskey(docs.meta, :results) || isempty(docs.meta[:results])
+        return docs
+    end
+    v = Any[]
+    for (n, doc) in enumerate(docs.content)
+        push!(v, doc)
+        n == length(docs.content) || push!(v, Markdown.HorizontalRule())
+    end
+    return Markdown.MD(v)
+end
+
 
 function repl_search(io::IO, s)
     pre = "search:"

Diff for: base/markdown/render/terminal/render.jl

@@ -107,7 +107,7 @@ function term(io::IO, br::LineBreak, columns)
 end
 
 function term(io::IO, br::HorizontalRule, columns)
-   println(io, " " ^ margin, "-" ^ (columns - 2margin))
+   println(io, " " ^ margin, "─" ^ (columns - 2margin))
 end
 
 term(io::IO, x, _) = show(io, MIME"text/plain"(), x)

Diff for: test/docs.jl

@@ -958,9 +958,9 @@ for (line, expr) in Pair[
     "\"...\""      => "...",
     "r\"...\""     => Expr(:macrocall, Symbol("@r_str"), LineNumberNode(1, :none), "...")
     ]
-    @test Docs.helpmode(line) == Expr(:macrocall, Expr(:., Expr(:., :Base, QuoteNode(:Docs)), QuoteNode(Symbol("@repl"))), LineNumberNode(115, doc_util_path), STDOUT, expr)
+    @test Docs._helpmode(line) == Expr(:macrocall, Expr(:., Expr(:., :Base, QuoteNode(:Docs)), QuoteNode(Symbol("@repl"))), LineNumberNode(119, doc_util_path), STDOUT, expr)
     buf = IOBuffer()
-    @test eval(Base, Docs.helpmode(buf, line)) isa Union{Base.Markdown.MD,Nothing}
+    @test eval(Base, Docs._helpmode(buf, line)) isa Union{Base.Markdown.MD,Nothing}
 end
 
 @test sprint(Base.Docs.repl_latex, "√") == "\"√\" can be typed by \\sqrt<tab>\n\n"
@@ -990,8 +990,8 @@ dynamic_test.x = "test 2"
 @test @doc(dynamic_test) == "test 2 Union{}"
 @test @doc(dynamic_test(::String)) == "test 2 Tuple{String}"
 
-@test Docs._repl(:(dynamic_test(1.0))) == Expr(:escape, Expr(:macrocall, Symbol("@doc"), LineNumberNode(196, doc_util_path), :(dynamic_test(::typeof(1.0)))))
-@test Docs._repl(:(dynamic_test(::String))) == Expr(:escape, Expr(:macrocall, Symbol("@doc"), LineNumberNode(196, doc_util_path), :(dynamic_test(::String))))
+@test Docs._repl(:(dynamic_test(1.0))) == Expr(:escape, Expr(:macrocall, Symbol("@doc"), LineNumberNode(214, doc_util_path), :(dynamic_test(::typeof(1.0)))))
+@test Docs._repl(:(dynamic_test(::String))) == Expr(:escape, Expr(:macrocall, Symbol("@doc"), LineNumberNode(214, doc_util_path), :(dynamic_test(::String))))