bpo-33216: Clarify the documentation for CALL_FUNCTION_* (#8338)

Clarify the documentation for the CALL_FUNCTION_* bytecodes. They changed in 3.5 in subtle ways and the documentation has never been correct, much less clear.

Author: larryhastings

Doc/library/dis.rst

@@ -960,34 +960,38 @@ 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)
 
  Pushes a new function object on the stack. From bottom to top, the consumed
  stack must consist of
 
- * ``argc & 0xFF`` default argument objects in positional order
+ * ``argc & 0xFF`` default argument objects in positional order, for positional parameters
  * ``(argc >> 8) & 0xFF`` pairs of name and default argument, with the name
  just below the object on the stack, for keyword-only parameters
  * ``(argc >> 16) & 0x7FFF`` parameter annotation objects
  * a tuple listing the parameter names for the annotations (only if there are
- ony annotation objects)
+ any annotation objects)
  * the code associated with the function (at TOS1)
  * the :term:`qualified name` of the function (at TOS)
 
@@ -1020,24 +1024,68 @@ 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 keyword arguments (if any), stored
+ identically to :opcode:`CALL_FUNCTION`.
+ Below that
+ is an iterable object containing additional positional arguments.
+ Below that are 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``.
+
+ .. versionchanged:: 3.5
+ In versions 3.0 to 3.4, the iterable object was above
+ the keyword arguments; in 3.5 the iterable object was moved
+ below the keyword arguments.
+
 
 
 .. 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 this 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 are keyword arguments (if any), stored
+ identically to :opcode:`CALL_FUNCTION`.
+ Below that
+ is an iterable object containing additional positional arguments.
+ Below that are 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``.
+
+ .. versionchanged:: 3.5
+ In versions 3.0 to 3.4, the iterable object was above
+ the keyword arguments; in 3.5 the iterable object was moved
+ below the keyword arguments.
 
 
 .. opcode:: HAVE_ARGUMENT
@@ -1071,7 +1119,7 @@ instructions:
 
 .. data:: hasconst
 
- Sequence of bytecodes that have a constant parameter.
+ Sequence of bytecodes that access a constant.
 
 
 .. data:: hasfree

Misc/NEWS.d/next/Documentation/2018-07-19-00-02-23.bpo-33216.YrBgBe.rst

@@ -0,0 +1,2 @@
+Clarify the documentation for CALL_FUNCTION_VAR, CALL_FUNCTION_KW, and
+CALL_FUNCTION_VAR_KW.