[2.7] bpo-33216: Clarify the documentation for CALL_FUNCTION_* (GH-8338) (GH-8783)

(cherry picked from commit 76aa2c0a9a8dd3ac90b91e7342c8ce8125bf21f9)

Co-authored-by: larryhastings <larry@hastings.org>

1 files changed, 53 insertions, 20 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 04b9b15386..e773ab8090 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -107,7 +107,7 @@ The :mod:`dis` module defines the following functions and constants:
 
 .. data:: hasconst
 
-   Sequence of bytecodes that have a constant parameter.
+   Sequence of bytecodes that access a constant.
 
 
 .. data:: hasfree
@@ -796,21 +796,25 @@ the more significant byte last.
 
 .. opcode:: RAISE_VARARGS (argc)
 
-   Raises an exception. *argc* indicates the number of parameters to the raise
+   Raises an exception. *argc* indicates the number of arguments to the raise
    statement, ranging from 0 to 3.  The handler will find the traceback as TOS2,
    the parameter as TOS1, and the exception as TOS.
 
 
 .. opcode:: CALL_FUNCTION (argc)
 
-   Calls a function.  The low byte of *argc* indicates the number of positional
-   parameters, the high byte the number of keyword parameters. On the stack, the
-   opcode finds the keyword parameters first.  For each keyword argument, the
-   value is on top of the key.  Below the keyword parameters, the positional
-   parameters are on the stack, with the right-most parameter on top.  Below the
-   parameters, the function object to call is on the stack.  Pops all function
-   arguments, and the function itself off the stack, and pushes the return
-   value.
+   Calls a callable object.  The low byte of *argc* indicates the number of
+   positional arguments, the high byte the number of keyword arguments.
+   The stack contains keyword arguments on top (if any), then the positional
+   arguments below that (if any), then the callable object to call below that.
+   Each keyword argument is represented with two values on the stack:
+   the argument's name, and its value, with the argument's value above the
+   name on the stack.
+   The positional arguments are pushed in the order that they are passed in
+   to the callable object, with the right-most positional argument on top.
+   ``CALL_FUNCTION`` pops all arguments and the callable object off the stack,
+   calls the callable object with those arguments, and pushes the return value
+   returned by the callable object.
 
 
 .. opcode:: MAKE_FUNCTION (argc)
@@ -847,24 +851,53 @@ the more significant byte last.
 
 .. opcode:: CALL_FUNCTION_VAR (argc)
 
-   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
-   top element on the stack contains the variable argument list, followed by
-   keyword and positional arguments.
+   Calls a callable object, similarly to :opcode:`CALL_FUNCTION`.
+   *argc* represents the number of keyword and positional
+   arguments, identically to :opcode:`CALL_FUNCTION`.
+   The top of the stack contains an iterable object containing
+   additional positional arguments.
+   Below that are keyword arguments (if any), positional arguments (if any)
+   and a callable object, identically to :opcode:`CALL_FUNCTION`.
+   Before the callable object is called, the iterable object
+   is "unpacked" and its contents are appended to the positional
+   arguments passed in.
+   The iterable object is ignored when computing
+   the value of ``argc``.
 
 
 .. opcode:: CALL_FUNCTION_KW (argc)
 
-   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`. The
-   top element on the stack contains the keyword arguments dictionary, followed
-   by explicit keyword and positional arguments.
+   Calls a callable object, similarly to :opcode:`CALL_FUNCTION`.
+   *argc* represents the number of keyword and positional
+   arguments, identically to :opcode:`CALL_FUNCTION`.
+   The top of the stack contains a mapping object containing additional keyword
+   arguments.
+   Below that are keyword arguments (if any), positional arguments (if any)
+   and a callable object, identically to :opcode:`CALL_FUNCTION`.
+   Before the callable is called, the mapping object at the top of the stack is
+   "unpacked" and its contents are appended to the keyword arguments passed in.
+   The mapping object at the top of the stack is ignored when computing
+   the value of ``argc``.
 
 
 .. opcode:: CALL_FUNCTION_VAR_KW (argc)
 
-   Calls a function. *argc* is interpreted as in :opcode:`CALL_FUNCTION`.  The
-   top element on the stack contains the keyword arguments dictionary, followed
-   by the variable-arguments tuple, followed by explicit keyword and positional
-   arguments.
+   Calls a callable object, similarly to :opcode:`CALL_FUNCTION_VAR` and
+   :opcode:`CALL_FUNCTION_KW`.
+   *argc* represents the number of keyword and positional
+   arguments, identically to :opcode:`CALL_FUNCTION`.
+   The top of the stack contains a mapping object, as per
+   :opcode:`CALL_FUNCTION_KW`.
+   Below that is an iterable object, as per
+   :opcode:`CALL_FUNCTION_VAR`.
+   Below that are keyword arguments (if any), positional arguments (if any)
+   and a callable object, identically to :opcode:`CALL_FUNCTION`.
+   Before the callable is called, the mapping object and iterable object
+   are each "unpacked" and their contents passed in as keyword and
+   positional arguments respectively,
+   identically to :opcode:`CALL_FUNCTION_VAR` and :opcode:`CALL_FUNCTION_KW`.
+   The mapping object and iterable object are both ignored when computing
+   the value of ``argc``.
 
 
 .. opcode:: HAVE_ARGUMENT ()