DOC: Doc for deprecate_with_doc (#17852)

* Add doc for deprecate_with_doc

Co-authored-by: Bas van Beek <43369155+BvB93@users.noreply.github.com>
Co-authored-by: Matti Picus <matti.picus@gmail.com>

2 files changed, 36 insertions, 2 deletions

diff --git a/numpy/lib/tests/test_utils.py b/numpy/lib/tests/test_utils.py
index 33951b92a..8a877ae69 100644
--- a/numpy/lib/tests/test_utils.py
+++ b/numpy/lib/tests/test_utils.py
@@ -4,7 +4,7 @@ import pytest
 
 from numpy.core import arange
 from numpy.testing import assert_, assert_equal, assert_raises_regex
-from numpy.lib import deprecate
+from numpy.lib import deprecate, deprecate_with_doc
 import numpy.lib.utils as utils
 
 from io import StringIO
@@ -60,6 +60,11 @@ def old_func6(self, x):
 new_func6 = deprecate(old_func6)
 
 
+@deprecate_with_doc(msg="Rather use new_func7")
+def old_func7(self,x):
+    return x
+
+
 def test_deprecate_decorator():
     assert_('deprecated' in old_func.__doc__)
 
@@ -73,6 +78,10 @@ def test_deprecate_fn():
     assert_('new_func3' in new_func3.__doc__)
 
 
+def test_deprecate_with_doc_decorator_message():
+    assert_('Rather use new_func7' in old_func7.__doc__)
+
+
 @pytest.mark.skipif(sys.flags.optimize == 2, reason="-OO discards docstrings")
 @pytest.mark.parametrize('old_func, new_func', [
     (old_func4, new_func4),
diff --git a/numpy/lib/utils.py b/numpy/lib/utils.py
index 5447608bf..f7e176cf3 100644
--- a/numpy/lib/utils.py
+++ b/numpy/lib/utils.py
@@ -193,7 +193,32 @@ def deprecate(*args, **kwargs):
     else:
         return _Deprecate(*args, **kwargs)
 
-deprecate_with_doc = lambda msg: _Deprecate(message=msg)
+
+def deprecate_with_doc(msg):
+    """
+    Deprecates a function and includes the deprecation in its docstring.
+    
+    This function is used as a decorator. It returns an object that can be 
+    used to issue a DeprecationWarning, by passing the to-be decorated 
+    function as argument, this adds warning to the to-be decorated function's 
+    docstring and returns the new function object.
+    
+    See Also
+    --------
+    deprecate : Decorate a function such that it issues a `DeprecationWarning` 
+    
+    Parameters
+    ----------
+    msg : str
+        Additional explanation of the deprecation. Displayed in the 
+        docstring after the warning.
+
+    Returns
+    -------
+    obj : object
+
+    """
+    return _Deprecate(message=msg)  
 
 
 #--------------------------------------------