[3.12] gh-101100: Improve documentation on function attributes (GH-112933) (#112974)

(cherry picked from commit 4c5b9c1)

Co-authored-by: Alex Waygood <[email protected]>

Author: hugovk

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)

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`.

Doc/howto/descriptor.rst

@@ -1332,7 +1332,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:
@@ -1543,8 +1544,9 @@ chained together.  In Python 3.11, this functionality was deprecated.
 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__

Doc/library/inspect.rst

@@ -1208,9 +1208,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

Doc/library/stdtypes.rst

@@ -5381,10 +5381,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::

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.

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