gh-101100: Properly document frame object attributes (#112735)

5 files changed, 11 insertions, 9 deletions

diff --git a/Doc/whatsnew/2.3.rst b/Doc/whatsnew/2.3.rst
index af332b2..c989e6d 100644
--- a/Doc/whatsnew/2.3.rst
+++ b/Doc/whatsnew/2.3.rst
@@ -1998,13 +1998,13 @@ Some of the more notable changes are:
   It would be difficult to detect any resulting difference from Python code, apart
   from a slight speed up when Python is run without :option:`-O`.
 
-  C extensions that access the :attr:`f_lineno` field of frame objects should
+  C extensions that access the :attr:`~frame.f_lineno` field of frame objects should
   instead call ``PyCode_Addr2Line(f->f_code, f->f_lasti)``. This will have the
   added effect of making the code work as desired under "python -O" in earlier
   versions of Python.
 
   A nifty new feature is that trace functions can now assign to the
-  :attr:`f_lineno` attribute of frame objects, changing the line that will be
+  :attr:`~frame.f_lineno` attribute of frame objects, changing the line that will be
   executed next.  A ``jump`` command has been added to the :mod:`pdb` debugger
   taking advantage of this new feature. (Implemented by Richie Hindle.)
 
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index df821d6..15479cc 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -399,7 +399,8 @@ PEP 626: Precise line numbers for debugging and other tools
 PEP 626 brings more precise and reliable line numbers for debugging, profiling and coverage tools.
 Tracing events, with the correct line number, are generated for all lines of code executed and only for lines of code that are executed.
 
-The ``f_lineno`` attribute of frame objects will always contain the expected line number.
+The :attr:`~frame.f_lineno` attribute of frame objects will always contain the
+expected line number.
 
 The ``co_lnotab`` attribute of code objects is deprecated and will be removed in 3.12.
 Code that needs to convert from offset to line number should use the new ``co_lines()`` method instead.
@@ -1959,11 +1960,11 @@ Changes in the C API
        source_buf = PyBytes_AsString(source_bytes_object);
        code = Py_CompileString(source_buf, filename, Py_file_input);
 
-  * For ``FrameObject`` objects, the ``f_lasti`` member now represents a wordcode
+  * For ``FrameObject`` objects, the :attr:`~frame.f_lasti` member now represents a wordcode
     offset instead of a simple offset into the bytecode string. This means that this
     number needs to be multiplied by 2 to be used with APIs that expect a byte offset
     instead (like :c:func:`PyCode_Addr2Line` for example). Notice as well that the
-    ``f_lasti`` member of ``FrameObject`` objects is not considered stable: please
+    :attr:`!f_lasti` member of ``FrameObject`` objects is not considered stable: please
     use :c:func:`PyFrame_GetLineNumber` instead.
 
 CPython bytecode changes
diff --git a/Doc/whatsnew/3.11.rst b/Doc/whatsnew/3.11.rst
index 48a0e62..8db133b 100644
--- a/Doc/whatsnew/3.11.rst
+++ b/Doc/whatsnew/3.11.rst
@@ -2458,11 +2458,12 @@ Porting to Python 3.11
   * ``f_valuestack``: removed.
 
   The Python frame object is now created lazily. A side effect is that the
-  ``f_back`` member must not be accessed directly, since its value is now also
+  :attr:`~frame.f_back` member must not be accessed directly,
+  since its value is now also
   computed lazily. The :c:func:`PyFrame_GetBack` function must be called
   instead.
 
-  Debuggers that accessed the ``f_locals`` directly *must* call
+  Debuggers that accessed the :attr:`~frame.f_locals` directly *must* call
   :c:func:`PyFrame_GetLocals` instead. They no longer need to call
   :c:func:`PyFrame_FastToLocalsWithError` or :c:func:`PyFrame_LocalsToFast`,
   in fact they should not call those functions. The necessary updating of the
diff --git a/Doc/whatsnew/3.6.rst b/Doc/whatsnew/3.6.rst
index c15d8be..2f61892 100644
--- a/Doc/whatsnew/3.6.rst
+++ b/Doc/whatsnew/3.6.rst
@@ -2162,7 +2162,7 @@ Changes in the Python API
 
 * The format of the ``co_lnotab`` attribute of code objects changed to support
   a negative line number delta. By default, Python does not emit bytecode with
-  a negative line number delta. Functions using ``frame.f_lineno``,
+  a negative line number delta. Functions using :attr:`frame.f_lineno`,
   ``PyFrame_GetLineNumber()`` or ``PyCode_Addr2Line()`` are not affected.
   Functions directly decoding ``co_lnotab`` should be updated to use a signed
   8-bit integer type for the line number delta, but this is only required to
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index a7d5c3d..99f280a 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -1891,7 +1891,7 @@ Other CPython Implementation Changes
 
 * Trace hooks may now opt out of receiving the ``line`` and opt into receiving
   the ``opcode`` events from the interpreter by setting the corresponding new
-  ``f_trace_lines`` and ``f_trace_opcodes`` attributes on the
+  :attr:`~frame.f_trace_lines` and :attr:`~frame.f_trace_opcodes` attributes on the
   frame being traced. (Contributed by Nick Coghlan in :issue:`31344`.)
 
 * Fixed some consistency problems with namespace package module attributes.