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

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

2 files changed, 111 insertions, 93 deletions

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__