[3.12] gh-101100: Improve documentation of code object attributes (#112781) (#112816)

(cherry-picked from commit e9707d3c3d)

1 files changed, 84 insertions, 30 deletions

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index efd999a..017b572 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1077,57 +1077,111 @@ indirectly) to mutable objects.
    single: co_freevars (code object attribute)
    single: co_qualname (code object attribute)
 
-Special read-only attributes: :attr:`co_name` gives the function name;
-:attr:`co_qualname` gives the fully qualified function name;
-:attr:`co_argcount` is the total number of positional arguments
-(including positional-only arguments and arguments with default values);
-:attr:`co_posonlyargcount` is the number of positional-only arguments
-(including arguments with default values); :attr:`co_kwonlyargcount` is
-the number of keyword-only arguments (including arguments with default
-values); :attr:`co_nlocals` is the number of local variables used by the
-function (including arguments); :attr:`co_varnames` is a tuple containing
-the names of the local variables (starting with the argument names);
-:attr:`co_cellvars` is a tuple containing the names of local variables
-that are referenced by nested functions; :attr:`co_freevars` is a tuple
-containing the names of free variables; :attr:`co_code` is a string
-representing the sequence of bytecode instructions; :attr:`co_consts` is
-a tuple containing the literals used by the bytecode; :attr:`co_names` is
-a tuple containing the names used by the bytecode; :attr:`co_filename` is
-the filename from which the code was compiled; :attr:`co_firstlineno` is
-the first line number of the function; :attr:`co_lnotab` is a string
-encoding the mapping from bytecode offsets to line numbers (for details
-see the source code of the interpreter, is deprecated since 3.12
-and may be removed in 3.14); :attr:`co_stacksize` is the
-required stack size; :attr:`co_flags` is an integer encoding a number
-of flags for the interpreter.
+Special read-only attributes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+
+   * - .. attribute:: codeobject.co_name
+     - The function name
+
+   * - .. attribute:: codeobject.co_qualname
+     - The fully qualified function name
+
+   * - .. attribute:: codeobject.co_argcount
+     - The total number of positional :term:`parameters <parameter>`
+       (including positional-only parameters and parameters with default values)
+       that the function has
+
+   * - .. attribute:: codeobject.co_posonlyargcount
+     - The number of positional-only :term:`parameters <parameter>`
+       (including arguments with default values) that the function has
+
+   * - .. attribute:: codeobject.co_kwonlyargcount
+     - The number of keyword-only :term:`parameters <parameter>`
+       (including arguments with default values) that the function has
+
+   * - .. attribute:: codeobject.co_nlocals
+     - The number of :ref:`local variables <naming>` used by the function
+       (including parameters)
+
+   * - .. attribute:: codeobject.co_varnames
+     - A :class:`tuple` containing the names of the local variables in the
+       function (starting with the parameter names)
+
+   * - .. attribute:: codeobject.co_cellvars
+     - A :class:`tuple` containing the names of :ref:`local variables <naming>`
+       that are referenced by nested functions inside the function
+
+   * - .. attribute:: codeobject.co_freevars
+     - A :class:`tuple` containing the names of free variables in the function
+
+   * - .. attribute:: codeobject.co_code
+     - A string representing the sequence of :term:`bytecode` instructions in
+       the function
+
+   * - .. attribute:: codeobject.co_consts
+     - A :class:`tuple` containing the literals used by the :term:`bytecode` in
+       the function
+
+   * - .. attribute:: codeobject.co_names
+     - A :class:`tuple` containing the names used by the :term:`bytecode` in
+       the function
+
+   * - .. attribute:: codeobject.co_filename
+     - The name of the file from which the code was compiled
+
+   * - .. attribute:: codeobject.co_firstlineno
+     - The line number of the first line of the function
+
+   * - .. attribute:: codeobject.co_lnotab
+     - A string encoding the mapping from :term:`bytecode` offsets to line
+       numbers. For details, see the source code of the interpreter.
+
+       .. deprecated:: 3.12
+          This attribute of code objects is deprecated, and may be removed in
+          Python 3.14.
+
+   * - .. attribute:: codeobject.co_stacksize
+     - The required stack size of the code object
+
+   * - .. attribute:: codeobject.co_flags
+     - An :class:`integer <int>` encoding a number of flags for the
+       interpreter.
 
 .. index:: pair: object; generator
 
-The following flag bits are defined for :attr:`co_flags`: bit ``0x04`` is set if
+The following flag bits are defined for :attr:`~codeobject.co_flags`:
+bit ``0x04`` is set if
 the function uses the ``*arguments`` syntax to accept an arbitrary number of
 positional arguments; bit ``0x08`` is set if the function uses the
 ``**keywords`` syntax to accept arbitrary keyword arguments; bit ``0x20`` is set
-if the function is a generator.
+if the function is a generator. See :ref:`inspect-module-co-flags` for details
+on the semantics of each flags that might be present.
 
 Future feature declarations (``from __future__ import division``) also use bits
-in :attr:`co_flags` to indicate whether a code object was compiled with a
+in :attr:`~codeobject.co_flags` to indicate whether a code object was compiled with a
 particular feature enabled: bit ``0x2000`` is set if the function was compiled
 with future division enabled; bits ``0x10`` and ``0x1000`` were used in earlier
 versions of Python.
 
-Other bits in :attr:`co_flags` are reserved for internal use.
+Other bits in :attr:`~codeobject.co_flags` are reserved for internal use.
 
 .. index:: single: documentation string
 
-If a code object represents a function, the first item in :attr:`co_consts` is
+If a code object represents a function, the first item in
+:attr:`~codeobject.co_consts` is
 the documentation string of the function, or ``None`` if undefined.
 
+The :meth:`!co_positions` method
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. method:: codeobject.co_positions()
 
-   Returns an iterable over the source code positions of each bytecode
+   Returns an iterable over the source code positions of each :term:`bytecode`
    instruction in the code object.
 
-   The iterator returns tuples containing the ``(start_line, end_line,
+   The iterator returns :class:`tuple`\s containing the ``(start_line, end_line,
    start_column, end_column)``. The *i-th* tuple corresponds to the
    position of the source code that compiled to the *i-th* instruction.
    Column information is 0-indexed utf-8 byte offsets on the given source