diff --git a/base/deprecated.jl b/base/deprecated.jl
index b0ce057d3a997..215563002dcc8 100644
--- a/base/deprecated.jl
+++ b/base/deprecated.jl
@@ -1485,8 +1485,11 @@ end
 using .DSP
 export conv, conv2, deconv, filt, filt!, xcorr
 
-# NOTE: rename the function replace_new from strings/util.jl to replace
-# when this replace is removed from deprecated.jl
+# PR #22325
+# TODO: when this replace is removed from deprecated.jl:
+# 1) rename the function replace_new from strings/util.jl to replace
+# 2) update the replace(s::AbstractString, pat, f) method, below replace_new
+#    (see instructions there)
 function replace(s::AbstractString, pat, f, n::Integer)
     if n <= 0
         depwarn(string("`replace(s, pat, r, count)` with `count <= 0` is deprecated, use ",
diff --git a/base/strings/util.jl b/base/strings/util.jl
index 17eb98a452bed..c30aa7a2de061 100644
--- a/base/strings/util.jl
+++ b/base/strings/util.jl
@@ -358,8 +358,8 @@ _replace(io, repl, str, r, pattern) = print(io, repl)
 _replace(io, repl::Function, str, r, pattern) =
     print(io, repl(SubString(str, first(r), last(r))))
 
+# TODO: rename to `replace` when `replace` is removed from deprecated.jl
 function replace_new(str::String, pattern, repl, count::Integer)
-    # rename to `replace` when `replace` is removed from deprecated.jl
     count == 0 && return str
     count < 0 && throw(DomainError())
     n = 1
@@ -405,7 +405,7 @@ If `pat` is a regular expression and `r` is a `SubstitutionString`, then capture
 references in `r` are replaced with the corresponding matched text.
 """
 replace(s::AbstractString, pat, f) = replace_new(String(s), pat, f, typemax(Int))
-# change this to the following when `replace` is removed from deprecated:
+# TODO: change this to the following when `replace` is removed from deprecated.jl:
 # replace(s::AbstractString, pat, f, count::Integer=typemax(Int)) =
 #     replace(String(s), pat, f, count)