@deprecate make part of comment into docstring (#29586)

Seems to be used a lot. https://github.com/search?q=deprecate+language%3Ajulia&type=Code

base/deprecated.jl

@@ -5,19 +5,21 @@
 # Please add new deprecations at the bottom of the file.
 # A function deprecated in a release will be removed in the next one.
 # Please also add a reference to the pull request which introduced the
-# deprecation.
-#
-# For simple cases where a direct replacement is available, use @deprecate:
-# the first argument is the signature of the deprecated method, the second one
-# is the call which replaces it. Remove the definition of the deprecated method
-# and unexport it, as @deprecate takes care of calling the replacement
+# deprecation. For simple cases where a direct replacement is available,
+# use @deprecate. @deprecate takes care of calling the replacement
 # and of exporting the function.
 #
 # For more complex cases, move the body of the deprecated method in this file,
 # and call depwarn() directly from inside it. The symbol depwarn() expects is
 # the name of the function, which is used to ensure that the deprecation warning
 # is only printed the first time for each call place.
 
+"""
+    @deprecate old new
+
+The first argument `old` is the signature of the deprecated method, the second one
+`new` is the call which replaces it. @deprecate exports the function.
+"""
 macro deprecate(old, new, ex=true)
     meta = Expr(:meta, :noinline)
     if isa(old, Symbol)