diff --git a/base/exports.jl b/base/exports.jl
index ec29cf58bc9ec..d25ee5b9d8887 100644
--- a/base/exports.jl
+++ b/base/exports.jl
@@ -84,6 +84,7 @@ export
     StridedVector,
     SubArray,
     SubString,
+    SubstitutionString,
     Timer,
     UnitRange,
     Val,
diff --git a/base/regex.jl b/base/regex.jl
index 8ea7efae92347..27a058c5f4572 100644
--- a/base/regex.jl
+++ b/base/regex.jl
@@ -230,6 +230,25 @@ findnext(r::Regex, s::AbstractString, idx::Integer) = throw(ArgumentError(
 ))
 findfirst(r::Regex, s::AbstractString) = findnext(r,s,firstindex(s))
 
+"""
+    SubstitutionString(substr)
+
+Stores the given string `substr` as a `SubstitutionString`, for use in regular expression
+substitutions. Most commonly constructed using the [`@s_str`](@ref) macro.
+
+```jldoctest
+julia> SubstitutionString("Hello \\\\g<name>, it's \\\\1")
+s"Hello \\\\g<name>, it's \\\\1"
+
+julia> subst = s"Hello \\g<name>, it's \\1"
+s"Hello \\\\g<name>, it's \\\\1"
+
+julia> typeof(subst)
+SubstitutionString{String}
+
+```
+
+"""
 struct SubstitutionString{T<:AbstractString} <: AbstractString
     string::T
 end
@@ -245,6 +264,20 @@ function show(io::IO, s::SubstitutionString)
     show(io, s.string)
 end
 
+"""
+    @s_str -> SubstitutionString
+
+Construct a substitution string, used for regular expression substitutions.  Within the
+string, sequences of the form `\\N` refer to the Nth capture group in the regex, and
+`\\g<groupname>` refers to a named capture group with name `groupname`.
+
+```jldoctest
+julia> msg = "#Hello# from Julia";
+
+julia> replace(msg, r"#(.+)# from (?<from>\\w+)" => s"FROM: \\g<from>; MESSAGE: \\1")
+"FROM: Julia; MESSAGE: Hello"
+```
+"""
 macro s_str(string) SubstitutionString(string) end
 
 replace_err(repl) = error("Bad replacement string: $repl")
diff --git a/base/strings/util.jl b/base/strings/util.jl
index 6e0f7790d4fce..0fcaf9f1f7ba4 100644
--- a/base/strings/util.jl
+++ b/base/strings/util.jl
@@ -452,7 +452,7 @@ or a regular expression.
 If `r` is a function, each occurrence is replaced with `r(s)`
 where `s` is the matched substring (when `pat`is a `Regex` or `AbstractString`) or
 character (when `pat` is an `AbstractChar` or a collection of `AbstractChar`).
-If `pat` is a regular expression and `r` is a `SubstitutionString`, then capture group
+If `pat` is a regular expression and `r` is a [`SubstitutionString`](@ref), then capture group
 references in `r` are replaced with the corresponding matched text.
 To remove instances of `pat` from `string`, set `r` to the empty `String` (`""`).
 
@@ -466,6 +466,9 @@ julia> replace("The quick foxes run quickly.", "quick" => "slow", count=1)
 
 julia> replace("The quick foxes run quickly.", "quick" => "", count=1)
 "The  foxes run quickly."
+
+julia> replace("The quick foxes run quickly.", r"fox(es)?" => s"bus\\1")
+"The quick buses run quickly."
 ```
 """
 replace(s::AbstractString, pat_f::Pair; count=typemax(Int)) =
diff --git a/doc/src/base/strings.md b/doc/src/base/strings.md
index d17827170b3ac..95e07e3180542 100644
--- a/doc/src/base/strings.md
+++ b/doc/src/base/strings.md
@@ -21,6 +21,8 @@ Base.codeunit
 Base.codeunits
 Base.ascii
 Base.@r_str
+Base.SubstitutionString
+Base.@s_str
 Base.@raw_str
 Base.Docs.@html_str
 Base.Docs.@text_str