Merge pull request #462 from ahojnnes/deprecated-doc-string

DOC: Change deprecated decorator to display warning in doc string.

skimage/_shared/utils.py

@@ -25,9 +25,12 @@ class deprecated(object):
 
     def __call__(self, func):
 
-        msg = "Call to deprecated function `%s`." % func.__name__
+        alt_msg = ''
         if self.alt_func is not None:
-            msg = msg + " Use `%s` instead." % self.alt_func
+            alt_msg = ' Use `%s` instead.' % self.alt_func
+
+        msg = 'Call to deprecated function `%s`.' % func.__name__
+        msg += alt_msg
 
         @functools.wraps(func)
         def wrapped(*args, **kwargs):
@@ -40,4 +43,11 @@ class deprecated(object):
                 raise DeprecationWarning(msg)
             return func(*args, **kwargs)
 
+        # modify doc string to display deprecation warning
+        doc = '**Deprecated function**.' + alt_msg
+        if wrapped.__doc__ is None:
+            wrapped.__doc__ = doc
+        else:
+            wrapped.__doc__ = doc + '\n\n' + wrapped.__doc__
+
         return wrapped