From 513d013d227c50fb8667c0472c396b317b82b73e Mon Sep 17 00:00:00 2001
From: Michael Tiemann <126827163+mitiemann@users.noreply.github.com>
Date: Sat, 6 Jan 2024 15:53:54 +0100
Subject: [PATCH] [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 <stevenj@mit.edu>
Co-authored-by: Jameson Nash <vtjnash@gmail.com>
Co-authored-by: Steven G. Johnson <stevenj@alum.mit.edu>
---
 stdlib/Markdown/docs/src/index.md  | 14 ++++++++++
 stdlib/Markdown/src/Markdown.jl    | 41 +++++++++++++++++++++++++++++-
 stdlib/Markdown/src/parse/parse.jl |  9 +++++++
 3 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/stdlib/Markdown/docs/src/index.md b/stdlib/Markdown/docs/src/index.md
index 30f530d1c6263..1913909278b54 100644
--- 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
index 781fcbdafddc8..93d8dbc39fc59 100644
--- 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
index 452d90d1176e1..0f3cbe857c2f9 100644
--- 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...)