From e73dfcdad0e9630a2b80d6bb4d947ee30bb947a0 Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Sat, 22 Nov 2025 10:32:17 -0500
Subject: [PATCH 1/3] Document stack effect APIs.

---
 Doc/c-api/veryhigh.rst | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 3b07b5fbed5959..ba66bf6417d652 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -396,3 +396,40 @@ Available start symbols
       * :pep:`484`
 
    .. versionadded:: 3.8
+
+
+Stack Effects
+^^^^^^^^^^^^^
+
+.. seealso::
+   :py:func:`dis.stack_effect`
+
+
+.. c:macro:: PY_INVALID_STACK_EFFECT
+
+   Sentinel value representing an invalid stack effect.
+
+   This is currently equivalent to ``INT_MAX``.
+
+   .. versionadded:: 3.8
+
+
+.. c:function:: int PyCompile_OpcodeStackEffect(int opcode, int oparg)
+
+   Compute the stack effect of *opcode* with argument *oparg*.
+
+   On success, this function returns the stack effect; on failure, this
+   returns :c:macro:`PY_INVALID_STACK_EFFECT`.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg)
+
+   Similar to :c:func:`PyCompile_OpcodeStackEffect`, but also includes the
+   stack effect of jumping.
+
+   On success, this function returns the stack effect; on failure, this
+   returns :c:macro:`PY_INVALID_STACK_EFFECT`.
+
+   .. versionadded:: 3.8

From 1bb20e3f6305f9d2d77b8cb4590371ee61167071 Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Sat, 22 Nov 2025 11:20:03 -0500
Subject: [PATCH 2/3] Document the jump parameter.

---
 Doc/c-api/veryhigh.rst | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index ba66bf6417d652..4d098310d52fbe 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -424,10 +424,13 @@ Stack Effects
    .. versionadded:: 3.4
 
 
-.. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg)
+.. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)
 
    Similar to :c:func:`PyCompile_OpcodeStackEffect`, but also includes the
-   stack effect of jumping.
+   stack effect of jumping depending on the value of *jump*.
+
+   If *jump* is ``0``, this will not include the stack effect of jumping, but
+   if *jump* is ``1`` or ``-1``, this will include it.
 
    On success, this function returns the stack effect; on failure, this
    returns :c:macro:`PY_INVALID_STACK_EFFECT`.

From ebc1d475a8ba2e3e762a9ae8cd278134eb18e0ef Mon Sep 17 00:00:00 2001
From: Peter Bierma <zintensitydev@gmail.com>
Date: Mon, 24 Nov 2025 11:32:20 -0500
Subject: [PATCH 3/3] Update Doc/c-api/veryhigh.rst

Co-authored-by: Victor Stinner <vstinner@python.org>
---
 Doc/c-api/veryhigh.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 4d098310d52fbe..7eb9f0b54abd4e 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -426,8 +426,8 @@ Stack Effects
 
 .. c:function:: int PyCompile_OpcodeStackEffectWithJump(int opcode, int oparg, int jump)
 
-   Similar to :c:func:`PyCompile_OpcodeStackEffect`, but also includes the
-   stack effect of jumping depending on the value of *jump*.
+   Similar to :c:func:`PyCompile_OpcodeStackEffect`, but don't include the
+   stack effect of jumping if *jump* is zero.
 
    If *jump* is ``0``, this will not include the stack effect of jumping, but
    if *jump* is ``1`` or ``-1``, this will include it.