gh-151456: Document the show_jit parameter in dis (#151457)

show_jit was added to dis.dis(), distb(), disassemble(), get_instructions() and the Bytecode class (gh-150478) but was never documented. Document it across those APIs with a versionchanged:: 3.16 note, and fix a pre-existing show_offset -> show_offsets typo in the distb signature.

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 3e7ae509fedcea6bb5475d59ef7c6d028533d4f2..4e1ba4327faec49084517540ac9fe702083b1389 100644 (file)
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -139,7 +139,7 @@ code.
 
 .. class:: Bytecode(x, *, first_line=None, current_offset=None,\
                     show_caches=False, adaptive=False, show_offsets=False,\
-                    show_positions=False)
+                    show_positions=False, show_jit=False)
 
    Analyse the bytecode corresponding to a function, generator, asynchronous
    generator, coroutine, method, string of source code, or a code object (as
@@ -170,6 +170,9 @@ code.
    If *show_positions* is ``True``, :meth:`.dis` will include instruction
    source code positions in the output.
 
+   If *show_jit* is ``True``, :meth:`.dis` will show ``ENTER_EXECUTOR``
+   instructions, which mark JIT entry points and are hidden by default.
+
    .. classmethod:: from_traceback(tb, *, show_caches=False)
 
       Construct a :class:`Bytecode` instance from the given traceback, setting
@@ -205,6 +208,9 @@ code.
    .. versionchanged:: 3.14
       Added the *show_positions* parameter.
 
+   .. versionchanged:: next
+      Added the *show_jit* parameter.
+
 Example:
 
 .. doctest::
@@ -259,7 +265,8 @@ operation is being performed, so the intermediate analysis object isn't useful:
 
 
 .. function:: dis(x=None, *, file=None, depth=None, show_caches=False,\
-                  adaptive=False, show_offsets=False, show_positions=False)
+                  adaptive=False, show_offsets=False, show_positions=False,\
+                  show_jit=False)
 
    Disassemble the *x* object.  *x* can denote either a module, a class, a
    method, a function, a generator, an asynchronous generator, a coroutine,
@@ -286,6 +293,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
    If *adaptive* is ``True``, this function will display specialized bytecode
    that may be different from the original bytecode.
 
+   If *show_jit* is ``True``, this function will show ``ENTER_EXECUTOR``
+   instructions, which mark JIT entry points and are hidden by default.
+
    .. versionchanged:: 3.4
       Added *file* parameter.
 
@@ -304,8 +314,11 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.14
       Added the *show_positions* parameter.
 
+   .. versionchanged:: next
+      Added the *show_jit* parameter.
+
 .. function:: distb(tb=None, *, file=None, show_caches=False, adaptive=False,\
-                    show_offset=False, show_positions=False)
+                    show_offsets=False, show_positions=False, show_jit=False)
 
    Disassemble the top-of-stack function of a traceback, using the last
    traceback if none was passed.  The instruction causing the exception is
@@ -326,10 +339,14 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.14
       Added the *show_positions* parameter.
 
+   .. versionchanged:: next
+      Added the *show_jit* parameter.
+
 .. function:: disassemble(code, lasti=-1, *, file=None, show_caches=False,\
-                          adaptive=False, show_offsets=False, show_positions=False)
+                          adaptive=False, show_offsets=False, show_positions=False,\
+                          show_jit=False)
               disco(code, lasti=-1, *, file=None, show_caches=False, adaptive=False,\
-                    show_offsets=False, show_positions=False)
+                    show_offsets=False, show_positions=False, show_jit=False)
 
    Disassemble a code object, indicating the last instruction if *lasti* was
    provided.  The output is divided in the following columns:
@@ -362,7 +379,10 @@ operation is being performed, so the intermediate analysis object isn't useful:
    .. versionchanged:: 3.14
       Added the *show_positions* parameter.
 
-.. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False)
+   .. versionchanged:: next
+      Added the *show_jit* parameter.
+
+.. function:: get_instructions(x, *, first_line=None, show_caches=False, adaptive=False, show_jit=False)
 
    Return an iterator over the instructions in the supplied function, method,
    source code string or code object.
@@ -377,6 +397,8 @@ operation is being performed, so the intermediate analysis object isn't useful:
 
    The *adaptive* parameter works as it does in :func:`dis`.
 
+   The *show_jit* parameter works as it does in :func:`dis`.
+
    .. versionadded:: 3.4
 
    .. versionchanged:: 3.11
@@ -388,6 +410,9 @@ operation is being performed, so the intermediate analysis object isn't useful:
       field populated (regardless of the value of *show_caches*) and it no longer
       generates separate items for the cache entries.
 
+   .. versionchanged:: next
+      Added the *show_jit* parameter.
+
 .. function:: findlinestarts(code)
 
    This generator function uses the :meth:`~codeobject.co_lines` method