From 22fcf43a22866bb4c75dd59d7f91ddf7ff2e8c2e Mon Sep 17 00:00:00 2001
From: Joris Van den Bossche <jorisvandenbossche@gmail.com>
Date: Tue, 14 Nov 2017 10:13:55 +0100
Subject: [PATCH] DOC/DEPR: ensure that @deprecated functions have correct
 docstring (#18215)

---
 pandas/core/series.py      | 4 ++--
 pandas/util/_decorators.py | 9 +++++++--
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/pandas/core/series.py b/pandas/core/series.py
index c9a72bb688270..9d56edd98d9f8 100644
--- a/pandas/core/series.py
+++ b/pandas/core/series.py
@@ -1361,13 +1361,13 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs):
 
     # ndarray compat
     argmin = deprecate('argmin', idxmin,
-                       msg="'argmin' is deprecated. Use 'idxmin' instead. "
+                       msg="'argmin' is deprecated, use 'idxmin' instead. "
                            "The behavior of 'argmin' will be corrected to "
                            "return the positional minimum in the future. "
                            "Use 'series.values.argmin' to get the position of "
                            "the minimum now.")
     argmax = deprecate('argmax', idxmax,
-                       msg="'argmax' is deprecated. Use 'idxmax' instead. "
+                       msg="'argmax' is deprecated, use 'idxmax' instead. "
                            "The behavior of 'argmax' will be corrected to "
                            "return the positional maximum in the future. "
                            "Use 'series.values.argmax' to get the position of "
diff --git a/pandas/util/_decorators.py b/pandas/util/_decorators.py
index 7c9250e52d482..6be6152b09fc8 100644
--- a/pandas/util/_decorators.py
+++ b/pandas/util/_decorators.py
@@ -3,7 +3,7 @@
 import inspect
 import types
 import warnings
-from textwrap import dedent
+from textwrap import dedent, wrap
 from functools import wraps, update_wrapper
 
 
@@ -29,11 +29,16 @@ def deprecate(name, alternative, alt_name=None, klass=None,
 
     alt_name = alt_name or alternative.__name__
     klass = klass or FutureWarning
-    msg = msg or "{} is deprecated. Use {} instead".format(name, alt_name)
+    msg = msg or "{} is deprecated, use {} instead".format(name, alt_name)
 
+    @wraps(alternative)
     def wrapper(*args, **kwargs):
         warnings.warn(msg, klass, stacklevel=stacklevel)
         return alternative(*args, **kwargs)
+
+    if getattr(wrapper, '__doc__', None) is not None:
+        wrapper.__doc__ = ('\n'.join(wrap(msg, 70)) + '\n'
+                           + dedent(wrapper.__doc__))
     return wrapper