Improve @deprecated's docstring.

anntzer · anntzer · commit c73e831fd1dc · 2019-06-15T17:04:41.000+02:00
- The example for `name` doesn't work (one would need
  ``old_function = deprecated("3.x", name="old_function")(new_function)
  but in practice that'll likely just be written using normal decorator
  syntax (there are no use cases of explicitly passing `name` in 3.1,
  AFAICT).
- `obj_type` is also automatically set for properties.
diff --git a/lib/matplotlib/cbook/deprecation.py b/lib/matplotlib/cbook/deprecation.py
@@ -135,15 +135,8 @@ def deprecated(since, *, message='', name='', alternative='', pending=False,
         object.
 
     name : str, optional
-        The name of the deprecated object; if not provided the name
-        is automatically determined from the passed in object,
-        though this is useful in the case of renamed functions, where
-        the new function is just assigned to the name of the
-        deprecated function.  For example::
-
-            def new_function():
-                ...
-            old_function = new_function
+        The name used in the deprecation message; if not provided, the name
+        is automatically determined from the deprecated object.
 
     alternative : str, optional
         An alternative API that the user may use in place of the deprecated
@@ -155,8 +148,8 @@ def new_function():
         DeprecationWarning.  Cannot be used together with *removal*.
 
     obj_type : str, optional
-        The object type being deprecated; by default, 'function' if decorating
-        a function and 'class' if decorating a class.
+        The object type being deprecated; by default, 'class' if decorating
+        a class, 'attribute' if decorating a property, 'function' otherwise.
 
     addendum : str, optional
         Additional text appended directly to the final message.
