[Markdown] added doc string for @md_str string literal (#52606)

This PR addresses #51168 . I guess this PR wants to have the labels doc & markdown . --------- Co-authored-by: Steven G. Johnson <[email protected]> Co-authored-by: Jameson Nash <[email protected]> Co-authored-by: Steven G. Johnson <[email protected]>
JuliaLang · Jan 6, 2024 · 513d013 · 513d013
1 parent c5dcf4f
commit 513d013
Show file tree

Hide file tree

Showing 3 changed files with 63 additions and 1 deletion.
diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
@@ -398,3 +398,17 @@ complex features (such as references) without cluttering the basic syntax.
 
 In principle, the Markdown parser itself can also be arbitrarily extended by packages, or an entirely
 custom flavour of Markdown can be used, but this should generally be unnecessary.
+
+## [Markdown String Literals](@id stdlib-markdown-literals)
+
+Markdown strings can be constructed using the string literal syntax `md"..."`.
+
+## [API reference](@id stdlib-markdown-api)
+
+```@docs
+Markdown.MD
+Markdown.@md_str
+Markdown.@doc_str
+Markdown.html
+Markdown.latex
+```
diff --git a/stdlib/Markdown/src/Markdown.jl b/stdlib/Markdown/src/Markdown.jl
@@ -1,7 +1,11 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 """
-Tools for working with the Markdown file format. Mainly for documentation.
+    Markdown
+
+Tools for working with the Markdown markup language for formatted text, used within Julia for documentation.
+The `Markdown` module provides the (internal) [`MD`](@ref) type as well as the string
+literals `md"..."` and `doc"..."`.
 """
 module Markdown
 
@@ -40,6 +44,22 @@ function docexpr(source::LineNumberNode, mod::Module, s, flavor = :julia)
     :($doc_str($(mdexpr(s, flavor)), $(QuoteNode(source)), $mod))
 end
 
+"""
+    @md_str -> MD
+
+Parse the given string as Markdown text and return a corresponding [`MD`](@ref) object.
+
+# Examples
+```jldoctest
+julia> s = md"# Hello, world!"
+  Hello, world!
+  ≡≡≡≡≡≡≡≡≡≡≡≡≡
+
+julia> typeof(s)
+Markdown.MD
+
+```
+"""
 macro md_str(s, t...)
     mdexpr(s, t...)
 end
@@ -51,6 +71,25 @@ function doc_str(md, source::LineNumberNode, mod::Module)
 end
 doc_str(md::AbstractString, source::LineNumberNode, mod::Module) = doc_str(parse(md), source, mod)
 
+"""
+    @doc_str -> MD
+
+Parse the given string as Markdown text, add line and module information and return a
+corresponding [`MD`](@ref) object.
+
+`@doc_str` can be used in conjunction with the [`Base.Docs`](@ref) module. Please also refer to
+the manual section on [documentation](@ref man-documentation) for more information.
+
+# Examples
+```
+julia> s = doc"f(x) = 2*x"
+  f(x) = 2*x
+
+julia> typeof(s)
+Markdown.MD
+
+```
+"""
 macro doc_str(s::AbstractString, t...)
     docexpr(__source__, __module__, s, t...)
 end

diff --git a/stdlib/Markdown/src/parse/parse.jl b/stdlib/Markdown/src/parse/parse.jl
@@ -1,5 +1,12 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+"""
+    MD
+
+`MD` represents a Markdown document. Note that the `MD` constructor should not generally be
+used directly, since it constructs the internal data structures. Instead, you can construct
+`MD` objects using the exported macros [`@md_str`](@ref) and [`@doc_str`](@ref).
+"""
 mutable struct MD
     content::Vector{Any}
     meta::Dict{Symbol, Any}
@@ -8,6 +15,8 @@ mutable struct MD
         new(content, meta)
 end
 
+public MD
+
 MD(xs...) = MD(vcat(xs...))
 
 function MD(cfg::Config, xs...)