Make Markdown.parse public and add a docstring (#56818)

Author: matthias314

stdlib/Markdown/docs/src/index.md

@@ -420,6 +420,7 @@ custom flavour of Markdown can be used, but this should generally be unnecessary
 Markdown.MD
 Markdown.@md_str
 Markdown.@doc_str
+Markdown.parse
 Markdown.html
 Markdown.latex
 ```

stdlib/Markdown/src/Common/block.jl

@@ -21,7 +21,7 @@ function paragraph(stream::IO, md::MD)
             char == '\r' && !eof(stream) && peek(stream, Char) == '\n' && read(stream, Char)
             if prev_char == '\\'
                 write(buffer, '\n')
-            elseif blankline(stream) || parse(stream, md, breaking = true)
+            elseif blankline(stream) || _parse(stream, md, breaking = true)
                 break
             else
                 write(buffer, ' ')

stdlib/Markdown/src/GitHub/GitHub.jl

@@ -44,7 +44,7 @@ function github_paragraph(stream::IO, md::MD)
     for char in readeach(stream, Char)
         if char == '\n'
             eof(stream) && break
-            if blankline(stream) || parse(stream, md, breaking = true)
+            if blankline(stream) || _parse(stream, md, breaking = true)
                 break
             else
                 write(buffer, '\n')

stdlib/Markdown/src/Markdown.jl

@@ -35,6 +35,8 @@ include("render/terminal/render.jl")
 
 export @md_str, @doc_str
 
+public MD, parse
+
 const MARKDOWN_FACES = [
     :markdown_header => Face(weight=:bold),
     :markdown_h1 => Face(height=1.25, inherit=:markdown_header),
@@ -57,7 +59,16 @@ const MARKDOWN_FACES = [
 __init__() = foreach(addface!, MARKDOWN_FACES)
 
 parse(markdown::String; flavor = julia) = parse(IOBuffer(markdown), flavor = flavor)
+
+"""
+    Markdown.parse(markdown::AbstractString) -> MD
+
+Parse `markdown` as Julia-flavored Markdown text and return the corresponding `MD` object.
+
+See also [`@md_str`](@ref).
+"""
 parse(markdown::AbstractString; flavor = julia) = parse(String(markdown), flavor = flavor)
+
 parse_file(file::AbstractString; flavor = julia) = parse(read(file, String), flavor = flavor)
 
 function mdexpr(s, flavor = :julia)
@@ -74,6 +85,8 @@ end
 
 Parse the given string as Markdown text and return a corresponding [`MD`](@ref) object.
 
+See also [`Markdown.parse`](@ref Markdown.parse(::AbstractString)).
+
 # Examples
 ```jldoctest
 julia> s = md"# Hello, world!"

stdlib/Markdown/src/parse/parse.jl

@@ -15,8 +15,6 @@ mutable struct MD
         new(content, meta)
 end
 
-public MD
-
 MD(xs...) = MD(vcat(xs...))
 
 function MD(cfg::Config, xs...)
@@ -85,7 +83,7 @@ parseinline(s, md::MD) = parseinline(s, md, config(md))
 
 # Block parsing
 
-function parse(stream::IO, block::MD, config::Config; breaking = false)
+function _parse(stream::IO, block::MD, config::Config; breaking = false)
     skipblank(stream)
     eof(stream) && return false
     for parser in (breaking ? config.breaking : [config.breaking; config.regular])
@@ -94,12 +92,17 @@ function parse(stream::IO, block::MD, config::Config; breaking = false)
     return false
 end
 
-parse(stream::IO, block::MD; breaking = false) =
-    parse(stream, block, config(block), breaking = breaking)
+_parse(stream::IO, block::MD; breaking = false) =
+    _parse(stream, block, config(block), breaking = breaking)
+
+"""
+    parse(stream::IO) -> MD
 
+Parse the content of `stream` as Julia-flavored Markdown text and return the corresponding `MD` object.
+"""
 function parse(stream::IO; flavor = julia)
     isa(flavor, Symbol) && (flavor = flavors[flavor])
     markdown = MD(flavor)
-    while parse(stream, markdown, flavor) end
+    while _parse(stream, markdown, flavor) end
     return markdown
 end