Shorten the @deprecated docs.

anntzer · anntzer · commit c2cf1c37a585 · 2021-07-19T11:58:28.000+02:00
For internal APIs, it seems reasonable to avoid the duplication of
the description of parameters (if anything, the shortened version makes
the difference in `obj_type`'s behavior clearer).

Also compress a bit the docstring of `warn_deprecated`.
diff --git a/lib/matplotlib/_api/deprecation.py b/lib/matplotlib/_api/deprecation.py
@@ -73,31 +73,24 @@ def warn_deprecated(
     ----------
     since : str
         The release at which this API became deprecated.
-
     message : str, optional
         Override the default deprecation message.  The ``%(since)s``,
         ``%(name)s``, ``%(alternative)s``, ``%(obj_type)s``, ``%(addendum)s``,
         and ``%(removal)s`` format specifiers will be replaced by the values
         of the respective arguments passed to this function.
-
     name : str, optional
         The name of the deprecated object.
-
     alternative : str, optional
         An alternative API that the user may use in place of the deprecated
         API.  The deprecation warning will tell the user about this alternative
         if provided.
-
     pending : bool, optional
         If True, uses a PendingDeprecationWarning instead of a
         DeprecationWarning.  Cannot be used together with *removal*.
-
     obj_type : str, optional
         The object type being deprecated.
-
     addendum : str, optional
         Additional text appended directly to the final message.
-
     removal : str, optional
         The expected removal version.  With the default (an empty string), a
         removal version is automatically computed from *since*.  Set to other
@@ -106,7 +99,7 @@ def warn_deprecated(
 
     Examples
     --------
-    Basic example::
+    ::
 
         # To warn of the deprecation of "matplotlib.name_of_module"
         warn_deprecated('1.4.0', name='matplotlib.name_of_module',
@@ -135,46 +128,13 @@ def deprecated(since, *, message='', name='', alternative='', pending=False,
     ``@deprecated`` would mess up ``__init__`` inheritance when installing its
     own (deprecation-emitting) ``C.__init__``).
 
-    Parameters
-    ----------
-    since : str
-        The release at which this API became deprecated.
-
-    message : str, optional
-        Override the default deprecation message.  The ``%(since)s``,
-        ``%(name)s``, ``%(alternative)s``, ``%(obj_type)s``, ``%(addendum)s``,
-        and ``%(removal)s`` format specifiers will be replaced by the values
-        of the respective arguments passed to this function.
-
-    name : str, optional
-        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
-        API.  The deprecation warning will tell the user about this alternative
-        if provided.
-
-    pending : bool, optional
-        If True, uses a PendingDeprecationWarning instead of a
-        DeprecationWarning.  Cannot be used together with *removal*.
-
-    obj_type : str, optional
-        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.
-
-    removal : str, optional
-        The expected removal version.  With the default (an empty string), a
-        removal version is automatically computed from *since*.  Set to other
-        Falsy values to not schedule a removal date.  Cannot be used together
-        with *pending*.
+    Parameters are the same as for `warn_deprecated`, except that *obj_type*
+    defaults to 'class' if decorating a class, 'attribute' if decorating a
+    property, and 'function' otherwise.
 
     Examples
     --------
-    Basic example::
+    ::
 
         @deprecated('1.4.0')
         def the_function_to_deprecate():
