improve TODO notes (StefanKarpinski)

Author: rfourquet

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 ",

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)