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>

1 files changed, 26 insertions, 1 deletions

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)  
 
 
 #--------------------------------------------