gh-105812: Make use of the Sphinx deco role in documentation, part 1

For the following decorators: `classmethod`, `staticmethod`,
`property`, ABC decorators, enum decorators, `functools.lru_cache`,
`functools.cache`.

Author: Viicos

Doc/c-api/structures.rst

@@ -419,8 +419,8 @@ method.
 
    The method will be passed the type object as the first parameter rather
    than an instance of the type.  This is used to create *class methods*,
-   similar to what is created when using the :func:`classmethod` built-in
-   function.
+   similar to what is created when using the :deco:`classmethod` built-in
+   decorator.
 
 
 .. c:macro:: METH_STATIC
@@ -429,7 +429,7 @@ method.
 
    The method will be passed ``NULL`` as the first parameter rather than an
    instance of the type.  This is used to create *static methods*, similar to
-   what is created when using the :func:`staticmethod` built-in function.
+   what is created when using the :deco:`staticmethod` built-in decorator.
 
 One other constant controls whether a method is loaded in place of another
 definition with the same method name.

Doc/faq/programming.rst

@@ -1995,7 +1995,7 @@ How do I cache method calls?
 ----------------------------
 
 The two principal tools for caching methods are
-:func:`functools.cached_property` and :func:`functools.lru_cache`.  The
+:deco:`functools.cached_property` and :deco:`functools.lru_cache`.  The
 former stores results at the instance level and the latter at the class
 level.
 

Doc/glossary.rst

@@ -366,7 +366,7 @@ Glossary
    decorator
       A function returning another function, usually applied as a function
       transformation using the ``@wrapper`` syntax.  Common examples for
-      decorators are :func:`classmethod` and :func:`staticmethod`.
+      decorators are :deco:`classmethod` and :deco:`staticmethod`.
 
       The decorator syntax is merely syntactic sugar, the following two
       function definitions are semantically equivalent::

Doc/howto/descriptor.rst

@@ -28,7 +28,7 @@ This guide has four major sections:
 4) The last section has pure Python equivalents for built-in descriptors that
    are written in C.  Read this if you're curious about how functions turn
    into bound methods or about the implementation of common tools like
-   :func:`classmethod`, :func:`staticmethod`, :func:`property`, and
+   :deco:`classmethod`, :deco:`staticmethod`, :deco:`property`, and
    :term:`__slots__`.
 
 
@@ -317,8 +317,8 @@ Descriptors invert that relationship and allow the data being looked-up to
 have a say in the matter.
 
 Descriptors are used throughout the language.  It is how functions turn into
-bound methods.  Common tools like :func:`classmethod`, :func:`staticmethod`,
-:func:`property`, and :func:`functools.cached_property` are all implemented as
+bound methods.  Common tools like :deco:`classmethod`, :deco:`staticmethod`,
+:deco:`property`, and :deco:`functools.cached_property` are all implemented as
 descriptors.
 
 
@@ -1326,7 +1326,7 @@ example calls are unexciting:
     30
 
 Using the non-data descriptor protocol, a pure Python version of
-:func:`staticmethod` would look like this:
+:deco:`staticmethod` would look like this:
 
 .. testcode::
 
@@ -1466,7 +1466,7 @@ Now a new dictionary of unique keys can be constructed like this:
     {'a': None, 'b': None, 'r': None, 'c': None, 'd': None}
 
 Using the non-data descriptor protocol, a pure Python version of
-:func:`classmethod` would look like this:
+:deco:`classmethod` would look like this:
 
 .. testcode::
 
@@ -1604,7 +1604,7 @@ matters when a large number of instances are going to be created.
 4. Improves speed.  Reading instance variables is 35% faster with
 ``__slots__`` (as measured with Python 3.10 on an Apple M1 processor).
 
-5. Blocks tools like :func:`functools.cached_property` which require an
+5. Blocks tools like :deco:`functools.cached_property` which require an
 instance dictionary to function correctly:
 
 .. testcode::

Doc/howto/enum.rst

@@ -256,7 +256,7 @@ Ensuring unique enumeration values
 ----------------------------------
 
 By default, enumerations allow multiple names as aliases for the same value.
-When this behavior isn't desired, you can use the :func:`unique` decorator::
+When this behavior isn't desired, you can use the :deco:`unique` decorator::
 
     >>> from enum import Enum, unique
     >>> @unique

Doc/library/abc.rst

@@ -170,17 +170,17 @@ The :mod:`!abc` module also provides the following decorator:
    or is derived from it.  A class that has a metaclass derived from
    :class:`!ABCMeta` cannot be instantiated unless all of its abstract methods
    and properties are overridden.  The abstract methods can be called using any
-   of the normal 'super' call mechanisms.  :func:`!abstractmethod` may be used
+   of the normal 'super' call mechanisms.  :deco:`!abstractmethod` may be used
    to declare abstract methods for properties and descriptors.
 
    Dynamically adding abstract methods to a class, or attempting to modify the
    abstraction status of a method or class once it is created, are only
    supported using the :func:`update_abstractmethods` function.  The
-   :func:`!abstractmethod` only affects subclasses derived using regular
+   :deco:`!abstractmethod` only affects subclasses derived using regular
    inheritance; "virtual subclasses" registered with the ABC's
    :meth:`~ABCMeta.register` method are not affected.
 
-   When :func:`!abstractmethod` is applied in combination with other method
+   When :deco:`!abstractmethod` is applied in combination with other method
    descriptors, it should be applied as the innermost decorator, as shown in
    the following usage examples::
 
@@ -218,7 +218,7 @@ The :mod:`!abc` module also provides the following decorator:
    the descriptor must identify itself as abstract using
    :attr:`!__isabstractmethod__`. In general, this attribute should be ``True``
    if any of the methods used to compose the descriptor are abstract. For
-   example, Python's built-in :class:`property` does the equivalent of::
+   example, Python's built-in :deco:`property` does the equivalent of::
 
       class Descriptor:
           ...
@@ -242,13 +242,13 @@ The :mod:`!abc` module also supports the following legacy decorators:
 
    .. versionadded:: 3.2
    .. deprecated:: 3.3
-       It is now possible to use :class:`classmethod` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`classmethod` with
+       :deco:`abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`classmethod`, indicating an abstract
-   classmethod. Otherwise it is similar to :func:`abstractmethod`.
+   A subclass of the built-in :class:`classmethod`, indicating an abstract
+   classmethod. Otherwise it is similar to :deco:`abstractmethod`.
 
-   This special case is deprecated, as the :func:`classmethod` decorator
+   This special case is deprecated, as the :deco:`classmethod` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 
@@ -263,13 +263,13 @@ The :mod:`!abc` module also supports the following legacy decorators:
 
    .. versionadded:: 3.2
    .. deprecated:: 3.3
-       It is now possible to use :class:`staticmethod` with
-       :func:`abstractmethod`, making this decorator redundant.
+       It is now possible to use :deco:`staticmethod` with
+       :deco:`abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`staticmethod`, indicating an abstract
-   staticmethod. Otherwise it is similar to :func:`abstractmethod`.
+   A subclass of the built-in :class:`staticmethod`, indicating an abstract
+   staticmethod. Otherwise it is similar to :deco:`abstractmethod`.
 
-   This special case is deprecated, as the :func:`staticmethod` decorator
+   This special case is deprecated, as the :deco:`staticmethod` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 
@@ -283,14 +283,14 @@ The :mod:`!abc` module also supports the following legacy decorators:
 .. decorator:: abstractproperty
 
    .. deprecated:: 3.3
-       It is now possible to use :class:`property`, :meth:`property.getter`,
+       It is now possible to use :deco:`property`, :meth:`property.getter`,
        :meth:`property.setter` and :meth:`property.deleter` with
-       :func:`abstractmethod`, making this decorator redundant.
+       :deco:`abstractmethod`, making this decorator redundant.
 
-   A subclass of the built-in :func:`property`, indicating an abstract
+   A subclass of the built-in :class:`property`, indicating an abstract
    property.
 
-   This special case is deprecated, as the :func:`property` decorator
+   This special case is deprecated, as the :deco:`property` decorator
    is now correctly identified as abstract when applied to an abstract
    method::
 

Doc/library/bisect.rst

@@ -132,7 +132,7 @@ thoughts in mind:
   they are used.  Consequently, if the search functions are used in a loop,
   the key function may be called again and again on the same array elements.
   If the key function isn't fast, consider wrapping it with
-  :py:func:`functools.cache` to avoid duplicate computations.  Alternatively,
+  :py:deco:`functools.cache` to avoid duplicate computations.  Alternatively,
   consider searching an array of precomputed keys to locate the insertion
   point (as shown in the examples section below).
 

Doc/library/collections.rst

@@ -1216,7 +1216,7 @@ original insertion position is changed and moved to the end::
             self.move_to_end(key)
 
 An :class:`OrderedDict` would also be useful for implementing
-variants of :func:`functools.lru_cache`:
+variants of :deco:`functools.lru_cache`:
 
 .. testcode::
 

Doc/library/contextlib.rst

@@ -88,7 +88,7 @@ Functions and classes provided:
    the exception has been handled, and execution will resume with the statement
    immediately following the :keyword:`!with` statement.
 
-   :func:`contextmanager` uses :class:`ContextDecorator` so the context managers
+   :deco:`contextmanager` uses :class:`ContextDecorator` so the context managers
    it creates can be used as decorators as well as in :keyword:`with` statements.
    When used as a decorator, a new generator instance is implicitly created on
    each function call (this allows the otherwise "one-shot" context managers

Doc/library/ctypes.rst

@@ -446,7 +446,7 @@ object with an :attr:`!_as_parameter_` attribute::
    >>>
 
 If you don't want to store the instance's data in the :attr:`!_as_parameter_`
-instance variable, you could define a :class:`property` which makes the
+instance variable, you could define a :deco:`property` which makes the
 attribute available on request.