DOC/DEPR: ensure that @deprecated functions have correct docstring (pandas-dev#18215)

Author: jorisvandenbossche

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 "

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