gh-101100: Improve documentation on function attributes (#112933)

Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>

14 files changed, 159 insertions, 130 deletions

diff --git a/Doc/c-api/function.rst b/Doc/c-api/function.rst
index 0a18e63..75a05b4 100644
--- a/Doc/c-api/function.rst
+++ b/Doc/c-api/function.rst
@@ -34,18 +34,20 @@ There are a few functions specific to Python functions.
    Return a new function object associated with the code object *code*. *globals*
    must be a dictionary with the global variables accessible to the function.
 
-   The function's docstring and name are retrieved from the code object. *__module__*
+   The function's docstring and name are retrieved from the code object.
+   :func:`~function.__module__`
    is retrieved from *globals*. The argument defaults, annotations and closure are
-   set to ``NULL``. *__qualname__* is set to the same value as the code object's
-   :attr:`~codeobject.co_qualname` field.
+   set to ``NULL``. :attr:`~function.__qualname__` is set to the same value as
+   the code object's :attr:`~codeobject.co_qualname` field.
 
 
 .. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
 
    As :c:func:`PyFunction_New`, but also allows setting the function object's
-   ``__qualname__`` attribute.  *qualname* should be a unicode object or ``NULL``;
-   if ``NULL``, the ``__qualname__`` attribute is set to the same value as the
-   code object's :attr:`~codeobject.co_qualname` field.
+   :attr:`~function.__qualname__` attribute.
+   *qualname* should be a unicode object or ``NULL``;
+   if ``NULL``, the :attr:`!__qualname__` attribute is set to the same value as
+   the code object's :attr:`~codeobject.co_qualname` field.
 
    .. versionadded:: 3.3
 
@@ -62,11 +64,12 @@ There are a few functions specific to Python functions.
 
 .. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
 
-   Return a :term:`borrowed reference` to the *__module__* attribute of the
-   function object *op*. It can be *NULL*.
+   Return a :term:`borrowed reference` to the :attr:`~function.__module__`
+   attribute of the :ref:`function object <user-defined-funcs>` *op*.
+   It can be *NULL*.
 
-   This is normally a string containing the module name, but can be set to any
-   other object by Python code.
+   This is normally a :class:`string <str>` containing the module name,
+   but can be set to any other object by Python code.
 
 
 .. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
diff --git a/Doc/howto/annotations.rst b/Doc/howto/annotations.rst
index 1134686..be8c7e6 100644
--- a/Doc/howto/annotations.rst
+++ b/Doc/howto/annotations.rst
@@ -153,7 +153,8 @@ on an arbitrary object ``o``:
   unwrap it by accessing either ``o.__wrapped__`` or ``o.func`` as
   appropriate, until you have found the root unwrapped function.
 * If ``o`` is a callable (but not a class), use
-  ``o.__globals__`` as the globals when calling :func:`eval`.
+  :attr:`o.__globals__ <function.__globals__>` as the globals when calling
+  :func:`eval`.
 
 However, not all string values used as annotations can
 be successfully turned into Python values by :func:`eval`.
diff --git a/Doc/howto/descriptor.rst b/Doc/howto/descriptor.rst
index f732aae..87274a5 100644
--- a/Doc/howto/descriptor.rst
+++ b/Doc/howto/descriptor.rst
@@ -1342,7 +1342,8 @@ Using the non-data descriptor protocol, a pure Python version of
 The :func:`functools.update_wrapper` call adds a ``__wrapped__`` attribute
 that refers to the underlying function.  Also it carries forward
 the attributes necessary to make the wrapper look like the wrapped
-function: ``__name__``, ``__qualname__``, ``__doc__``, and ``__annotations__``.
+function: :attr:`~function.__name__`, :attr:`~function.__qualname__`,
+:attr:`~function.__doc__`, and :attr:`~function.__annotations__`.
 
 .. testcode::
     :hide:
@@ -1522,8 +1523,9 @@ Using the non-data descriptor protocol, a pure Python version of
 The :func:`functools.update_wrapper` call in ``ClassMethod`` adds a
 ``__wrapped__`` attribute that refers to the underlying function.  Also
 it carries forward the attributes necessary to make the wrapper look
-like the wrapped function: ``__name__``, ``__qualname__``, ``__doc__``,
-and ``__annotations__``.
+like the wrapped function: :attr:`~function.__name__`,
+:attr:`~function.__qualname__`, :attr:`~function.__doc__`,
+and :attr:`~function.__annotations__`.
 
 
 Member objects and __slots__
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 8381e50..f8b3e39 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -1225,9 +1225,10 @@ Classes and functions
    * If ``obj`` is a class, ``globals`` defaults to
      ``sys.modules[obj.__module__].__dict__`` and ``locals`` defaults
      to the ``obj`` class namespace.
-   * If ``obj`` is a callable, ``globals`` defaults to ``obj.__globals__``,
+   * If ``obj`` is a callable, ``globals`` defaults to
+     :attr:`obj.__globals__ <function.__globals__>`,
      although if ``obj`` is a wrapped function (using
-     ``functools.update_wrapper()``) it is first unwrapped.
+     :func:`functools.update_wrapper`) it is first unwrapped.
 
    Calling ``get_annotations`` is best practice for accessing the
    annotations dict of any object.  See :ref:`annotations-howto` for
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 399238c..9028ff5 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -5384,10 +5384,10 @@ Code objects are used by the implementation to represent "pseudo-compiled"
 executable Python code such as a function body. They differ from function
 objects because they don't contain a reference to their global execution
 environment.  Code objects are returned by the built-in :func:`compile` function
-and can be extracted from function objects through their :attr:`__code__`
-attribute. See also the :mod:`code` module.
+and can be extracted from function objects through their
+:attr:`~function.__code__` attribute. See also the :mod:`code` module.
 
-Accessing ``__code__`` raises an :ref:`auditing event <auditing>`
+Accessing :attr:`~function.__code__` raises an :ref:`auditing event <auditing>`
 ``object.__getattr__`` with arguments ``obj`` and ``"__code__"``.
 
 .. index::
diff --git a/Doc/library/xmlrpc.server.rst b/Doc/library/xmlrpc.server.rst
index 016369d..ca1ea45 100644
--- a/Doc/library/xmlrpc.server.rst
+++ b/Doc/library/xmlrpc.server.rst
@@ -84,12 +84,12 @@ alone XML-RPC servers.
 
    Register a function that can respond to XML-RPC requests.  If *name* is given,
    it will be the method name associated with *function*, otherwise
-   ``function.__name__`` will be used.  *name* is a string, and may contain
+   :attr:`function.__name__` will be used.  *name* is a string, and may contain
    characters not legal in Python identifiers, including the period character.
 
    This method can also be used as a decorator.  When used as a decorator,
    *name* can only be given as a keyword argument to register *function* under
-   *name*.  If no *name* is given, ``function.__name__`` will be used.
+   *name*.  If no *name* is given, :attr:`function.__name__` will be used.
 
    .. versionchanged:: 3.7
       :meth:`register_function` can be used as a decorator.
@@ -298,12 +298,12 @@ requests sent to Python CGI scripts.
 
    Register a function that can respond to XML-RPC requests.  If *name* is given,
    it will be the method name associated with *function*, otherwise
-   ``function.__name__`` will be used.  *name* is a string, and may contain
+   :attr:`function.__name__` will be used.  *name* is a string, and may contain
    characters not legal in Python identifiers, including the period character.
 
    This method can also be used as a decorator.  When used as a decorator,
    *name* can only be given as a keyword argument to register *function* under
-   *name*.  If no *name* is given, ``function.__name__`` will be used.
+   *name*.  If no *name* is given, :attr:`function.__name__` will be used.
 
    .. versionchanged:: 3.7
       :meth:`register_function` can be used as a decorator.
diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst
index 8f64813..7a73509 100644
--- a/Doc/reference/compound_stmts.rst
+++ b/Doc/reference/compound_stmts.rst
@@ -1261,7 +1261,8 @@ except that the original function is not temporarily bound to the name ``func``.
 A list of :ref:`type parameters <type-params>` may be given in square brackets
 between the function's name and the opening parenthesis for its parameter list.
 This indicates to static type checkers that the function is generic. At runtime,
-the type parameters can be retrieved from the function's ``__type_params__``
+the type parameters can be retrieved from the function's
+:attr:`~function.__type_params__`
 attribute. See :ref:`generic-functions` for more.
 
 .. versionchanged:: 3.12
@@ -1868,8 +1869,8 @@ like ``TYPE_PARAMS_OF_ListOrSet`` are not actually bound at runtime.
    are mappings.
 
 .. [#] A string literal appearing as the first statement in the function body is
-   transformed into the function's ``__doc__`` attribute and therefore the
-   function's :term:`docstring`.
+   transformed into the function's :attr:`~function.__doc__` attribute and
+   therefore the function's :term:`docstring`.
 
 .. [#] A string literal appearing as the first statement in the class body is
    transformed into the namespace's ``__doc__`` item and therefore the class's
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 4db3f6b..de79d72 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -534,9 +534,34 @@ section :ref:`function`).  It should be called with an argument list
 containing the same number of items as the function's formal parameter
 list.
 
-Special attributes:
+Special read-only attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. index::
+   single: __closure__ (function attribute)
+   single: __globals__ (function attribute)
+   pair: global; namespace
+
+.. list-table::
+   :header-rows: 1
 
-.. tabularcolumns:: |l|L|l|
+   * - Attribute
+     - Meaning
+
+   * - .. attribute:: function.__globals__
+     - A reference to the :class:`dictionary <dict>` that holds the function's
+       :ref:`global variables <naming>` -- the global namespace of the module
+       in which the function was defined.
+
+   * - .. attribute:: function.__closure__
+     - ``None`` or a :class:`tuple` of cells that contain bindings for the
+       function's free variables.
+
+       A cell object has the attribute ``cell_contents``.
+       This can be used to get the value of the cell, as well as set the value.
+
+Special writable attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. index::
    single: __doc__ (function attribute)
@@ -544,96 +569,78 @@ Special attributes:
    single: __module__ (function attribute)
    single: __dict__ (function attribute)
    single: __defaults__ (function attribute)
-   single: __closure__ (function attribute)
    single: __code__ (function attribute)
-   single: __globals__ (function attribute)
    single: __annotations__ (function attribute)
    single: __kwdefaults__ (function attribute)
    single: __type_params__ (function attribute)
-   pair: global; namespace
 
-+-------------------------+-------------------------------+-----------+
-| Attribute               | Meaning                       |           |
-+=========================+===============================+===========+
-| :attr:`__doc__`         | The function's documentation  | Writable  |
-|                         | string, or ``None`` if        |           |
-|                         | unavailable; not inherited by |           |
-|                         | subclasses.                   |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`~definition.\    | The function's name.          | Writable  |
-| __name__`               |                               |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`~definition.\    | The function's                | Writable  |
-| __qualname__`           | :term:`qualified name`.       |           |
-|                         |                               |           |
-|                         | .. versionadded:: 3.3         |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__module__`      | The name of the module the    | Writable  |
-|                         | function was defined in, or   |           |
-|                         | ``None`` if unavailable.      |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__defaults__`    | A tuple containing default    | Writable  |
-|                         | argument values for those     |           |
-|                         | arguments that have defaults, |           |
-|                         | or ``None`` if no arguments   |           |
-|                         | have a default value.         |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__code__`        | The code object representing  | Writable  |
-|                         | the compiled function body.   |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__globals__`     | A reference to the dictionary | Read-only |
-|                         | that holds the function's     |           |
-|                         | global variables --- the      |           |
-|                         | global namespace of the       |           |
-|                         | module in which the function  |           |
-|                         | was defined.                  |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`~object.__dict__`| The namespace supporting      | Writable  |
-|                         | arbitrary function            |           |
-|                         | attributes.                   |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__closure__`     | ``None`` or a tuple of cells  | Read-only |
-|                         | that contain bindings for the |           |
-|                         | function's free variables.    |           |
-|                         | See below for information on  |           |
-|                         | the ``cell_contents``         |           |
-|                         | attribute.                    |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__annotations__` | A dict containing annotations | Writable  |
-|                         | of parameters.  The keys of   |           |
-|                         | the dict are the parameter    |           |
-|                         | names, and ``'return'`` for   |           |
-|                         | the return annotation, if     |           |
-|                         | provided.  For more           |           |
-|                         | information on working with   |           |
-|                         | this attribute, see           |           |
-|                         | :ref:`annotations-howto`.     |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__kwdefaults__`  | A dict containing defaults    | Writable  |
-|                         | for keyword-only parameters.  |           |
-+-------------------------+-------------------------------+-----------+
-| :attr:`__type_params__` | A tuple containing the        | Writable  |
-|                         | :ref:`type parameters         |           |
-|                         | <type-params>` of a           |           |
-|                         | :ref:`generic function        |           |
-|                         | <generic-functions>`.         |           |
-+-------------------------+-------------------------------+-----------+
-
-Most of the attributes labelled "Writable" check the type of the assigned value.
+Most of these attributes check the type of the assigned value:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Attribute
+     - Meaning
+
+   * - .. attribute:: function.__doc__
+     - The function's documentation string, or ``None`` if unavailable.
+       Not inherited by subclasses.
+
+   * - .. attribute:: function.__name__
+     - The function's name.
+       See also: :attr:`__name__ attributes <definition.__name__>`.
+
+   * - .. attribute:: function.__qualname__
+     - The function's :term:`qualified name`.
+       See also: :attr:`__qualname__ attributes <definition.__qualname__>`.
+
+       .. versionadded:: 3.3
+
+   * - .. attribute:: function.__module__
+     - The name of the module the function was defined in,
+       or ``None`` if unavailable.
+
+   * - .. attribute:: function.__defaults__
+     - A :class:`tuple` containing default parameter values
+       for those parameters that have defaults,
+       or ``None`` if no parameters have a default value.
+
+   * - .. attribute:: function.__code__
+     - The :ref:`code object <code-objects>` representing
+       the compiled function body.
+
+   * - .. attribute:: function.__dict__
+     - The namespace supporting arbitrary function attributes.
+       See also: :attr:`__dict__ attributes <object.__dict__>`.
+
+   * - .. attribute:: function.__annotations__
+     - A :class:`dictionary <dict>` containing annotations of parameters.
+       The keys of the dictionary are the parameter names,
+       and ``'return'`` for the return annotation, if provided.
+       See also: :ref:`annotations-howto`.
+
+   * - .. attribute:: function.__kwdefaults__
+     - A :class:`dictionary <dict>` containing defaults for keyword-only
+       parameters.
+
+   * - .. attribute:: function.__type_params__
+     - A :class:`tuple` containing the :ref:`type parameters <type-params>` of
+       a :ref:`generic function <generic-functions>`.
 
 Function objects also support getting and setting arbitrary attributes, which
 can be used, for example, to attach metadata to functions.  Regular attribute
-dot-notation is used to get and set such attributes. *Note that the current
-implementation only supports function attributes on user-defined functions.
-Function attributes on built-in functions may be supported in the future.*
+dot-notation is used to get and set such attributes.
 
-A cell object has the attribute ``cell_contents``. This can be used to get
-the value of the cell, as well as set the value.
+.. impl-detail::
+
+   CPython's current implementation only supports function attributes
+   on user-defined functions. Function attributes on
+   :ref:`built-in functions <builtin-functions>` may be supported in the
+   future.
 
 Additional information about a function's definition can be retrieved from its
-code object; see the description of internal types below. The
-:data:`cell <types.CellType>` type can be accessed in the :mod:`types`
-module.
+:ref:`code object <code-objects>`
+(accessible via the :attr:`~function.__code__` attribute).
 
 
 .. _instance-methods:
@@ -665,15 +672,17 @@ Special read-only attributes:
        :ref:`bound <method-binding>`
 
    * - .. attribute:: method.__func__
-     - Refers to the original function object
+     - Refers to the original :ref:`function object <user-defined-funcs>`
 
    * - .. attribute:: method.__doc__
-     - The method's documentation (same as :attr:`!method.__func__.__doc__`).
+     - The method's documentation
+       (same as :attr:`method.__func__.__doc__ <function.__doc__>`).
        A :class:`string <str>` if the original function had a docstring, else
        ``None``.
 
    * - .. attribute:: method.__name__
-     - The name of the method (same as :attr:`!method.__func__.__name__`)
+     - The name of the method
+       (same as :attr:`method.__func__.__name__ <function.__name__>`)
 
    * - .. attribute:: method.__module__
      - The name of the module the method was defined in, or ``None`` if
@@ -779,6 +788,8 @@ is raised and the asynchronous iterator will have reached the end of
 the set of values to be yielded.
 
 
+.. _builtin-functions:
+
 Built-in functions
 ^^^^^^^^^^^^^^^^^^
 
@@ -791,10 +802,14 @@ A built-in function object is a wrapper around a C function.  Examples of
 built-in functions are :func:`len` and :func:`math.sin` (:mod:`math` is a
 standard built-in module). The number and type of the arguments are
 determined by the C function. Special read-only attributes:
-:attr:`__doc__` is the function's documentation string, or ``None`` if
-unavailable; :attr:`~definition.__name__` is the function's name; :attr:`__self__` is
-set to ``None`` (but see the next item); :attr:`__module__` is the name of
-the module the function was defined in or ``None`` if unavailable.
+
+* :attr:`!__doc__` is the function's documentation string, or ``None`` if
+  unavailable. See :attr:`function.__doc__`.
+* :attr:`!__name__` is the function's name. See :attr:`function.__name__`.
+* :attr:`!__self__` is set to ``None`` (but see the next item).
+* :attr:`!__module__` is the name of
+  the module the function was defined in or ``None`` if unavailable.
+  See :attr:`function.__module__`.
 
 
 .. _builtin-methods:
@@ -844,7 +859,8 @@ the :ref:`import system <importsystem>` as invoked either by the
 :keyword:`import` statement, or by calling
 functions such as :func:`importlib.import_module` and built-in
 :func:`__import__`.  A module object has a namespace implemented by a
-dictionary object (this is the dictionary referenced by the ``__globals__``
+:class:`dictionary <dict>` object (this is the dictionary referenced by the
+:attr:`~function.__globals__`
 attribute of functions defined in the module).  Attribute references are
 translated to lookups in this dictionary, e.g., ``m.x`` is equivalent to
 ``m.__dict__["x"]``. A module object does not contain the code object used
@@ -1891,7 +1907,8 @@ access (use of, assignment to, or deletion of ``x.name``) for class instances.
    .. note::
 
       This method may still be bypassed when looking up special methods as the
-      result of implicit invocation via language syntax or built-in functions.
+      result of implicit invocation via language syntax or
+      :ref:`built-in functions <builtin-functions>`.
       See :ref:`special-lookup`.
 
    .. audit-event:: object.__getattr__ obj,name object.__getattribute__
diff --git a/Doc/whatsnew/2.1.rst b/Doc/whatsnew/2.1.rst
index f0e1ded..6d2d3cc 100644
--- a/Doc/whatsnew/2.1.rst
+++ b/Doc/whatsnew/2.1.rst
@@ -424,7 +424,8 @@ PEP 232: Function Attributes
 
 In Python 2.1, functions can now have arbitrary information attached to them.
 People were often using docstrings to hold information about functions and
-methods, because the ``__doc__`` attribute was the only way of attaching any
+methods, because the :attr:`~function.__doc__` attribute was the only way of
+attaching any
 information to a function.  For example, in the Zope web application server,
 functions are marked as safe for public access by having a docstring, and in
 John Aycock's SPARK parsing framework, docstrings hold parts of the BNF grammar
diff --git a/Doc/whatsnew/2.4.rst b/Doc/whatsnew/2.4.rst
index cab321c..a7b0c6e 100644
--- a/Doc/whatsnew/2.4.rst
+++ b/Doc/whatsnew/2.4.rst
@@ -324,7 +324,8 @@ function, as previously described.  In other words, ``@A @B @C(args)`` becomes::
 
 Getting this right can be slightly brain-bending, but it's not too difficult.
 
-A small related change makes the :attr:`func_name` attribute of functions
+A small related change makes the :attr:`func_name <function.__name__>`
+attribute of functions
 writable.  This attribute is used to display function names in tracebacks, so
 decorators should change the name of any new function that's constructed and
 returned.
diff --git a/Doc/whatsnew/3.0.rst b/Doc/whatsnew/3.0.rst
index b0c2529..5953b32 100644
--- a/Doc/whatsnew/3.0.rst
+++ b/Doc/whatsnew/3.0.rst
@@ -779,14 +779,15 @@ Operators And Special Methods
 
 * Removed support for :attr:`__members__` and :attr:`__methods__`.
 
-* The function attributes named :attr:`func_X` have been renamed to
-  use the :data:`__X__` form, freeing up these names in the function
+* The function attributes named :attr:`!func_X` have been renamed to
+  use the :attr:`!__X__` form, freeing up these names in the function
   attribute namespace for user-defined attributes.  To wit,
-  :attr:`func_closure`, :attr:`func_code`, :attr:`func_defaults`,
-  :attr:`func_dict`, :attr:`func_doc`, :attr:`func_globals`,
-  :attr:`func_name` were renamed to :attr:`__closure__`,
-  :attr:`__code__`, :attr:`__defaults__`, :attr:`~object.__dict__`,
-  :attr:`__doc__`, :attr:`__globals__`, :attr:`~definition.__name__`,
+  :attr:`!func_closure`, :attr:`!func_code`, :attr:`!func_defaults`,
+  :attr:`!func_dict`, :attr:`!func_doc`, :attr:`!func_globals`,
+  :attr:`!func_name` were renamed to :attr:`~function.__closure__`,
+  :attr:`~function.__code__`, :attr:`~function.__defaults__`,
+  :attr:`~function.__dict__`, :attr:`~function.__doc__`,
+  :attr:`~function.__globals__`, :attr:`~function.__name__`,
   respectively.
 
 * :meth:`!__nonzero__` is now :meth:`~object.__bool__`.
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 4401deb..00f3968 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -483,7 +483,7 @@ Deprecated
   (as has always been the case for an executing frame).
   (Contributed by Irit Katriel in :gh:`79932`.)
 
-* Assignment to a function's ``__code__`` attribute where the new code
+* Assignment to a function's :attr:`~function.__code__` attribute where the new code
   object's type does not match the function's type, is deprecated. The
   different types are: plain function, generator, async generator and
   coroutine.
diff --git a/Doc/whatsnew/3.2.rst b/Doc/whatsnew/3.2.rst
index df32b76..5ef7696 100644
--- a/Doc/whatsnew/3.2.rst
+++ b/Doc/whatsnew/3.2.rst
@@ -791,8 +791,9 @@ functools
 
 * The :func:`functools.wraps` decorator now adds a :attr:`__wrapped__` attribute
   pointing to the original callable function.  This allows wrapped functions to
-  be introspected.  It also copies :attr:`__annotations__` if defined.  And now
-  it also gracefully skips over missing attributes such as :attr:`__doc__` which
+  be introspected.  It also copies :attr:`~function.__annotations__` if
+  defined.  And now it also gracefully skips over missing attributes such as
+  :attr:`~function.__doc__` which
   might not be defined for the wrapped callable.
 
   In the above example, the cache can be removed by recovering the original
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 2ddab76..9f9cf7f 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -2405,8 +2405,8 @@ Changes in the Python API
   storage).  (:issue:`17094`.)
 
 * Parameter names in ``__annotations__`` dicts are now mangled properly,
-  similarly to ``__kwdefaults__``.  (Contributed by Yury Selivanov in
-  :issue:`20625`.)
+  similarly to :attr:`~function.__kwdefaults__`.
+  (Contributed by Yury Selivanov in :issue:`20625`.)
 
 * :attr:`hashlib.hash.name` now always returns the identifier in lower case.
   Previously some builtin hashes had uppercase names, but now that it is a