Documenter.mdparse(md; mode=:single) unexpectedly returns list

[goerz]

Maybe I'm just misreading the documentation for Documenter.mdparse where it says that ":single (default) – returns a single block-level object", but I'm finding the function to return a single-element list:

using Documenter  # master
using MarkdownAST
using Test

MD_MINIMAL = raw"""
Text with [rabiner_tutorial_1989](@cite).
"""

@testset "Documenter.mdparse" begin
    minimal_block_ast = MarkdownAST.@ast MarkdownAST.Paragraph() do
        MarkdownAST.Text("Text with ")
        MarkdownAST.Link("@cite", "") do
            MarkdownAST.Text("rabiner")
            MarkdownAST.Emph() do
                MarkdownAST.Text("tutorial")
            end
            MarkdownAST.Text("1989")
        end
        MarkdownAST.Text(".")
    end
    @test_broken Documenter.mdparse(MD_MINIMAL; mode=:single) == minimal_block_ast
    @test Documenter.mdparse(MD_MINIMAL; mode=:single) == [minimal_block_ast] # XXX
    @test Documenter.mdparse(MD_MINIMAL; mode=:blocks) == [minimal_block_ast]
    @test Documenter.mdparse(MD_MINIMAL; mode=:span) == [minimal_block_ast.children...]
end

For markdown with multiple blocks, :single throws an error (as documented).

In principle, it would make the most sense to me if mode=:single were to return the Paragraph() node directly. On the other hand, I suppose always returning a list is more type stable. But then the documentation should be changed.

I might want to use mdparse with mode=:single in DocumenterCitations, so it would be good to clarify what the intended interface is.

[goerz]

Oh, I just realized the function is indeed annotated as returning Vector{MarkdownAST.Node{Nothing}}. So this must be intentional, for type stability.

I'll assume it will stay that way, then (but maybe I'll submit a tiny PR to update the documentation).

[mortenpi]

To be honest, I don't remember why it works now the way it does, and this is very much an internal function. Probably for consistency, yes. But I did apparently forget to fully updated the docstring, so a PR to bring the up to speed with reality is always welcome.