Update comments and docs in responce to the review.

Author: serhiy-storchaka

Doc/library/dis.rst

@@ -681,17 +681,18 @@ iterations of the loop.
      used to restore the exception state.  An exception handler block is
      removed from the block stack.
 
-   It is similar to :opcode:`END_FINALLY`, but neither change the bytecode
-   counter nor raises an exception.  Used for implementing :keyword:`break`
+   It is similar to :opcode:`END_FINALLY`, but doesn't change the bytecode
+   counter nor raise an exception.  Used for implementing :keyword:`break`
    and :keyword:`return` in the :keyword:`finally` block.
 
    .. versionadded:: 3.7
 
 
 .. opcode:: BEGIN_FINALLY
 
-   Pushes ``NULL`` onto the stack for using it in :opcode:`END_FINALLY`.
-   Starts the :keyword:`finally` block.
+   Pushes ``NULL`` onto the stack for using it in :opcode:`END_FINALLY`,
+   :opcode:`POP_FINALLY`, :opcode:`WITH_CLEANUP_START` and
+   :opcode:`WITH_CLEANUP_FINISH`.  Starts the :keyword:`finally` block.
 
    .. versionadded:: 3.7
 

Python/ceval.c

@@ -1899,6 +1899,16 @@ _PyEval_EvalFrameDefault(PyFrameObject *f, int throwflag)
         }
 
         TARGET(POP_FINALLY) {
+            /* If oparg is 0 at the top of the stack are 1 or 6 values:
+               Either:
+                - TOP = NULL or an integer
+               or:
+                - (TOP, SECOND, THIRD) = exc_info()
+                - (FOURTH, FITH, SIXTH) = previous exception for EXCEPT_HANDLER
+
+               If oparg is 1 the value for 'return' was additionally pushed
+               at the top of the stack.
+            */
             PyObject *res = NULL;
             if (oparg) {
                 res = POP();
@@ -1950,6 +1960,9 @@ _PyEval_EvalFrameDefault(PyFrameObject *f, int throwflag)
         }
 
         TARGET(BEGIN_FINALLY) {
+            /* Push NULL onto the stack for using it in END_FINALLY,
+               POP_FINALLY, WITH_CLEANUP_START and WITH_CLEANUP_FINISH.
+             */
             PUSH(NULL);
             FAST_DISPATCH();
         }
@@ -1958,7 +1971,7 @@ _PyEval_EvalFrameDefault(PyFrameObject *f, int throwflag)
         TARGET(END_FINALLY) {
             /* At the top of the stack are 1 or 6 values:
                Either:
-                - NULL or an integer
+                - TOP = NULL or an integer
                or:
                 - (TOP, SECOND, THIRD) = exc_info()
                 - (FOURTH, FITH, SIXTH) = previous exception for EXCEPT_HANDLER

Python/compile.c

@@ -1036,7 +1036,9 @@ PyCompile_OpcodeStackEffect(int opcode, int oparg)
             return 6;
         case BEGIN_FINALLY:
             /* Actually pushes 1 value, but count 6 for balancing with
-             * END_FINALLY and POP_FINALLY. */
+             * END_FINALLY and POP_FINALLY.
+             * This is the main reason of using this opcode instead of
+             * "LOAD_CONST None". */
             return 6;
         case CALL_FINALLY:
             return 1;