[3.14] gh-105812: Use the `:deco:` role in place of manual decorator markup (GH-139619) (#139627)

(cherry picked from commit 3195da0b1a)

Doc/library/collections.abc.rst

@@ -336,7 +336,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
    .. note::
       In CPython, generator-based coroutines (:term:`generators <generator>`
-      decorated with :func:`@types.coroutine <types.coroutine>`) are
+      decorated with :deco:`types.coroutine`) are
       *awaitables*, even though they do not have an :meth:`~object.__await__` method.
       Using ``isinstance(gencoro, Awaitable)`` for them will return ``False``.
       Use :func:`inspect.isawaitable` to detect them.
@@ -354,7 +354,7 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
    .. note::
       In CPython, generator-based coroutines (:term:`generators <generator>`
-      decorated with :func:`@types.coroutine <types.coroutine>`) are
+      decorated with :deco:`types.coroutine`) are
       *awaitables*, even though they do not have an :meth:`~object.__await__` method.
       Using ``isinstance(gencoro, Coroutine)`` for them will return ``False``.
       Use :func:`inspect.isawaitable` to detect them.

Doc/library/dataclasses.rst

@@ -317,7 +317,7 @@ Module contents
    :func:`!field`, then the class attribute for this field will be
    replaced by the specified *default* value.  If *default* is not
    provided, then the class attribute will be deleted.  The intent is
-   that after the :func:`@dataclass <dataclass>` decorator runs, the class
+   that after the :deco:`dataclass` decorator runs, the class
    attributes will all contain the default values for the fields, just
    as if the default value itself were specified.  For example,
    after::
@@ -427,7 +427,7 @@ Module contents
    :data:`typing.Any` is used for ``type``.  The values of *init*,
    *repr*, *eq*, *order*, *unsafe_hash*, *frozen*,
    *match_args*, *kw_only*, *slots*, and *weakref_slot* have
-   the same meaning as they do in :func:`@dataclass <dataclass>`.
+   the same meaning as they do in :deco:`dataclass`.
 
    If *module* is defined, the :attr:`!__module__` attribute
    of the dataclass is set to that value.
@@ -435,12 +435,12 @@ Module contents
 
    The *decorator* parameter is a callable that will be used to create the dataclass.
    It should take the class object as a first argument and the same keyword arguments
-   as :func:`@dataclass <dataclass>`. By default, the :func:`@dataclass <dataclass>`
+   as :deco:`dataclass`. By default, the :deco:`dataclass`
    function is used.
 
    This function is not strictly required, because any Python
    mechanism for creating a new class with :attr:`~object.__annotations__` can
-   then apply the :func:`@dataclass <dataclass>` function to convert that class to
+   then apply the :deco:`dataclass` function to convert that class to
    a dataclass.  This function is provided as a convenience.  For
    example::
 
@@ -569,7 +569,7 @@ Post-init processing
          def __post_init__(self):
              self.c = self.a + self.b
 
-The :meth:`~object.__init__` method generated by :func:`@dataclass <dataclass>` does not call base
+The :meth:`~object.__init__` method generated by :deco:`dataclass` does not call base
 class :meth:`!__init__` methods. If the base class has an :meth:`!__init__` method
 that has to be called, it is common to call this method in a
 :meth:`__post_init__` method::
@@ -599,7 +599,7 @@ parameters to :meth:`!__post_init__`.  Also see the warning about how
 Class variables
 ---------------
 
-One of the few places where :func:`@dataclass <dataclass>` actually inspects the type
+One of the few places where :deco:`dataclass` actually inspects the type
 of a field is to determine if a field is a class variable as defined
 in :pep:`526`.  It does this by checking if the type of the field is
 :data:`typing.ClassVar`.  If a field is a ``ClassVar``, it is excluded
@@ -612,7 +612,7 @@ module-level :func:`fields` function.
 Init-only variables
 -------------------
 
-Another place where :func:`@dataclass <dataclass>` inspects a type annotation is to
+Another place where :deco:`dataclass` inspects a type annotation is to
 determine if a field is an init-only variable.  It does this by seeing
 if the type of a field is of type :class:`InitVar`.  If a field
 is an :class:`InitVar`, it is considered a pseudo-field called an init-only
@@ -646,7 +646,7 @@ Frozen instances
 ----------------
 
 It is not possible to create truly immutable Python objects.  However,
-by passing ``frozen=True`` to the :func:`@dataclass <dataclass>` decorator you can
+by passing ``frozen=True`` to the :deco:`dataclass` decorator you can
 emulate immutability.  In that case, dataclasses will add
 :meth:`~object.__setattr__` and :meth:`~object.__delattr__` methods to the class.  These
 methods will raise a :exc:`FrozenInstanceError` when invoked.
@@ -662,7 +662,7 @@ must use :meth:`!object.__setattr__`.
 Inheritance
 -----------
 
-When the dataclass is being created by the :func:`@dataclass <dataclass>` decorator,
+When the dataclass is being created by the :deco:`dataclass` decorator,
 it looks through all of the class's base classes in reverse MRO (that
 is, starting at :class:`object`) and, for each dataclass that it finds,
 adds the fields from that base class to an ordered mapping of fields.
@@ -786,7 +786,7 @@ for :attr:`!x` when creating a class instance will share the same copy
 of :attr:`!x`.  Because dataclasses just use normal Python class
 creation they also share this behavior.  There is no general way
 for Data Classes to detect this condition.  Instead, the
-:func:`@dataclass <dataclass>` decorator will raise a :exc:`ValueError` if it
+:deco:`dataclass` decorator will raise a :exc:`ValueError` if it
 detects an unhashable default parameter.  The assumption is that if
 a value is unhashable, it is mutable.  This is a partial solution,
 but it does protect against many common errors.
@@ -820,7 +820,7 @@ default value have the following special behaviors:
   :meth:`~object.__get__` or :meth:`!__set__` method is called rather than returning or
   overwriting the descriptor object.
 
-* To determine whether a field contains a default value, :func:`@dataclass <dataclass>`
+* To determine whether a field contains a default value, :deco:`dataclass`
   will call the descriptor's :meth:`!__get__` method using its class access
   form: ``descriptor.__get__(obj=None, type=cls)``.  If the
   descriptor returns a value in this case, it will be used as the

Doc/library/functools.rst

@@ -690,7 +690,7 @@ The :mod:`functools` module defines the following functions:
             return not arg
 
    ``@singledispatchmethod`` supports nesting with other decorators such as
-   :func:`@classmethod<classmethod>`. Note that to allow for
+   :deco:`classmethod`. Note that to allow for
    ``dispatcher.register``, ``singledispatchmethod`` must be the *outer most*
    decorator. Here is the ``Negator`` class with the ``neg`` methods bound to
    the class, rather than an instance of the class::
@@ -712,8 +712,7 @@ The :mod:`functools` module defines the following functions:
             return not arg
 
    The same pattern can be used for other similar decorators:
-   :func:`@staticmethod<staticmethod>`,
-   :func:`@abstractmethod<abc.abstractmethod>`, and others.
+   :deco:`staticmethod`, :deco:`~abc.abstractmethod`, and others.
 
    .. versionadded:: 3.8
 

Doc/library/typing.rst

@@ -1390,7 +1390,7 @@ These can be used as types in annotations. They all support subscription using
    Using ``Annotated[T, x]`` as an annotation still allows for static
    typechecking of ``T``, as type checkers will simply ignore the metadata ``x``.
    In this way, ``Annotated`` differs from the
-   :func:`@no_type_check <no_type_check>` decorator, which can also be used for
+   :deco:`no_type_check` decorator, which can also be used for
    adding annotations outside the scope of the typing system, but
    completely disables typechecking for a function or class.
 
@@ -2835,7 +2835,7 @@ Protocols
 ---------
 
 The following protocols are provided by the :mod:`!typing` module. All are decorated
-with :func:`@runtime_checkable <runtime_checkable>`.
+with :deco:`runtime_checkable`.
 
 .. class:: SupportsAbs
 
@@ -3016,7 +3016,7 @@ Functions and decorators
    The presence of ``@dataclass_transform()`` tells a static type checker that the
    decorated object performs runtime "magic" that
    transforms a class in a similar way to
-   :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
+   :deco:`dataclasses.dataclass`.
 
    Example usage with a decorator function:
 
@@ -3054,14 +3054,14 @@ Functions and decorators
 
    The ``CustomerModel`` classes defined above will
    be treated by type checkers similarly to classes created with
-   :func:`@dataclasses.dataclass <dataclasses.dataclass>`.
+   :deco:`dataclasses.dataclass`.
    For example, type checkers will assume these classes have
    ``__init__`` methods that accept ``id`` and ``name``.
 
    The decorated class, metaclass, or function may accept the following bool
    arguments which type checkers will assume have the same effect as they
    would have on the
-   :func:`@dataclasses.dataclass<dataclasses.dataclass>` decorator: ``init``,
+   :deco:`dataclasses.dataclass` decorator: ``init``,
    ``eq``, ``order``, ``unsafe_hash``, ``frozen``, ``match_args``,
    ``kw_only``, and ``slots``. It must be possible for the value of these
    arguments (``True`` or ``False``) to be statically evaluated.
@@ -3189,12 +3189,12 @@ Functions and decorators
 
 .. function:: get_overloads(func)
 
-   Return a sequence of :func:`@overload <overload>`-decorated definitions for
+   Return a sequence of :deco:`overload`-decorated definitions for
    *func*.
 
    *func* is the function object for the implementation of the
    overloaded function. For example, given the definition of ``process`` in
-   the documentation for :func:`@overload <overload>`,
+   the documentation for :deco:`overload`,
    ``get_overloads(process)`` will return a sequence of three function objects
    for the three defined overloads. If called on a function with no overloads,
    ``get_overloads()`` returns an empty sequence.
@@ -3351,7 +3351,7 @@ Introspection helpers
      If *globalns* or *localns* is not given, appropriate namespace
      dictionaries are inferred from *obj*.
    * ``None`` is replaced with :class:`types.NoneType`.
-   * If :func:`@no_type_check <no_type_check>` has been applied to *obj*, an
+   * If :deco:`no_type_check` has been applied to *obj*, an
      empty dictionary is returned.
    * If *obj* is a class ``C``, the function returns a dictionary that merges
      annotations from ``C``'s base classes with those on ``C`` directly. This

Doc/library/warnings.rst

@@ -586,7 +586,7 @@ Available Functions
    The deprecation message passed to the decorator is saved in the
    ``__deprecated__`` attribute on the decorated object.
    If applied to an overload, the decorator
-   must be after the :func:`@overload <typing.overload>` decorator
+   must be after the :deco:`~typing.overload` decorator
    for the attribute to exist on the overload as returned by
    :func:`typing.get_overloads`.
 

Doc/reference/datamodel.rst

@@ -2558,7 +2558,7 @@ instance dictionary.  In contrast, non-data descriptors can be overridden by
 instances.
 
 Python methods (including those decorated with
-:func:`@staticmethod <staticmethod>` and :func:`@classmethod <classmethod>`) are
+:deco:`staticmethod` and :deco:`classmethod`) are
 implemented as non-data descriptors.  Accordingly, instances can redefine and
 override methods.  This allows individual instances to acquire behaviors that
 differ from other instances of the same class.
@@ -2991,7 +2991,7 @@ class method ``__class_getitem__()``.
 
    When defined on a class, ``__class_getitem__()`` is automatically a class
    method. As such, there is no need for it to be decorated with
-   :func:`@classmethod<classmethod>` when it is defined.
+   :deco:`classmethod` when it is defined.
 
 
 The purpose of *__class_getitem__*

Doc/whatsnew/2.7.rst

@@ -858,8 +858,8 @@ Some smaller changes made to the core Python language are:
 
   .. XXX bytearray doesn't seem to be documented
 
-* When using :class:`@classmethod <classmethod>` and
-  :class:`@staticmethod <staticmethod>` to wrap
+* When using :deco:`classmethod` and
+  :deco:`staticmethod` to wrap
   methods as class or static methods, the wrapper object now
   exposes the wrapped function as their :attr:`~method.__func__`
   attribute.

Doc/whatsnew/3.10.rst

@@ -847,8 +847,8 @@ Other Language Changes
   respectively.
   (Contributed by Joshua Bronson, Daniel Pope, and Justin Wang in :issue:`31861`.)
 
-* Static methods (:func:`@staticmethod <staticmethod>`) and class methods
-  (:func:`@classmethod <classmethod>`) now inherit the method attributes
+* Static methods (:deco:`staticmethod`) and class methods
+  (:deco:`classmethod`) now inherit the method attributes
   (``__module__``, ``__name__``, ``__qualname__``, ``__doc__``,
   ``__annotations__``) and have a new ``__wrapped__`` attribute.
   Moreover, static methods are now callable as regular functions.

Misc/NEWS.d/3.10.0b1.rst

@@ -402,8 +402,8 @@ the heap. Should speed up dispatch in the interpreter.
 .. nonce: eUn4p5
 .. section: Core and Builtins
 
-Static methods (:func:`@staticmethod <staticmethod>`) and class methods
-(:func:`@classmethod <classmethod>`) now inherit the method attributes
+Static methods (:deco:`staticmethod`) and class methods
+(:deco:`classmethod`) now inherit the method attributes
 (``__module__``, ``__name__``, ``__qualname__``, ``__doc__``,
 ``__annotations__``) and have a new ``__wrapped__`` attribute. Patch by
 Victor Stinner.
@@ -454,7 +454,7 @@ file locations.
 .. nonce: VSF3vg
 .. section: Core and Builtins
 
-Static methods (:func:`@staticmethod <staticmethod>`) are now callable as
+Static methods (:deco:`staticmethod`) are now callable as
 regular functions. Patch by Victor Stinner.
 
 ..

Misc/NEWS.d/3.11.0a1.rst

@@ -2953,7 +2953,7 @@ support for Metadata 2.2.
 .. nonce: xTUyyX
 .. section: Library
 
-Remove the :func:`@asyncio.coroutine <asyncio.coroutine>` :term:`decorator`
+Remove the :deco:`asyncio.coroutine` :term:`decorator`
 enabling legacy generator-based coroutines to be compatible with async/await
 code; remove :class:`asyncio.coroutines.CoroWrapper` used for wrapping
 legacy coroutine objects in the debug mode. The decorator has been

Misc/NEWS.d/3.11.0b1.rst

@@ -664,7 +664,7 @@ for :func:`os.fcopyfile` available in macOs.
 .. nonce: l1p7CJ
 .. section: Library
 
-For :func:`@dataclass <dataclasses.dataclass>`, add *weakref_slot*.
+For :deco:`~dataclasses.dataclass`, add *weakref_slot*.
 The new parameter defaults to ``False``. If true, and if
 ``slots=True``, add a slot named ``"__weakref__"``, which will allow instances to be
 weakref'd. Contributed by Eric V. Smith

Misc/NEWS.d/3.14.0a1.rst

@@ -1999,7 +1999,7 @@ with an escape character.
 .. nonce: vi2bP-
 .. section: Library
 
-:func:`@warnings.deprecated <warnings.deprecated>` now copies the coroutine
+:deco:`warnings.deprecated` now copies the coroutine
 status of functions and methods so that :func:`inspect.iscoroutinefunction`
 returns the correct result.