bpo-28810: Document changes to CALL_FUNCTION opcodes (GH-607)

(cherry picked from commit 4b2a2a425a906c8e4eb8daee14ab1793e225f726)

1 files changed, 39 insertions, 30 deletions

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 686118f..11d0569 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -1009,14 +1009,45 @@ All of the following opcodes use their arguments.
 
 .. 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 function.  *argc* indicates the number of positional arguments.
+   The positional arguments are on the stack, with the right-most argument
+   on top.  Below the arguments, 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.
+
+   .. versionchanged:: 3.6
+      This opcode is used only for calls with positional arguments.
+
+
+.. opcode:: CALL_FUNCTION_KW (argc)
+
+   Calls a function.  *argc* indicates the number of arguments (positional
+   and keyword).  The top element on the stack contains a tuple of keyword
+   argument names.  Below the tuple, keyword arguments are on the stack, in
+   the order corresponding to the tuple.  Below the keyword arguments, the
+   positional arguments are on the stack, with the right-most parameter on
+   top.  Below the arguments, 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.
+
+   .. versionchanged:: 3.6
+      Keyword arguments are packed in a tuple instead of a dictionary,
+      *argc* indicates the total number of arguments
+
+
+.. opcode:: CALL_FUNCTION_EX (flags)
+
+   Calls a function. The lowest bit of *flags* indicates whether the
+   var-keyword argument is placed at the top of the stack.  Below the
+   var-keyword argument, the var-positional argument is on the stack.
+   Below the arguments, the function object to call is placed.
+   Pops all function arguments, and the function itself off the stack, and
+   pushes the return value. Note that this opcode pops at most three items
+   from the stack. Var-positional and var-keyword arguments are packed
+   by :opcode:`BUILD_MAP_UNPACK_WITH_CALL` and
+   :opcode:`BUILD_MAP_UNPACK_WITH_CALL`.
+
+   .. versionadded:: 3.6
 
 
 .. opcode:: MAKE_FUNCTION (argc)
@@ -1049,28 +1080,6 @@ All of the following opcodes use their arguments.
    two most-significant bytes.
 
 
-.. 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.
-
-
-.. 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.
-
-
-.. 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.
-
-
 .. opcode:: FORMAT_VALUE (flags)
 
    Used for implementing formatted literal strings (f-strings).  Pops