From: Michele Angrisano <michele.angrisano@gmail.com>
Date: Sun, 2 Jun 2019 21:34:12 +0000 (+0200)
Subject: bpo-19184: Update the documentation of dis module. (GH-13652)
X-Git-Tag: v3.8.0b1~47
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e1179a5096fb12297ececd7a1c79969aa5747e28;p=thirdparty%2FPython%2Fcpython.git

bpo-19184: Update the documentation of dis module. (GH-13652)

* bpo-19184: Update the documentation of dis module

* Explain the behavior of the number of arguments of RAISE_VARGARGS
  opcode.

* bpo-19184: Update blurb.

* bpo-19184: Fix typo in the dis Documentation.

* bpo-19184: Address review comments and improve the doc

* bpo-19184: Remove news file.
---

diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst
index 060d4bb6997a..15e707ae49f8 100644
--- a/Doc/library/dis.rst
+++ b/Doc/library/dis.rst
@@ -1113,9 +1113,13 @@ All of the following opcodes use their arguments.
 
 .. opcode:: RAISE_VARARGS (argc)
 
-   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.
+   Raises an exception using one of the 3 forms of the ``raise`` statement,
+   depending on the value of *argc*:
+
+   * 0: ``raise`` (re-raise previous exception)
+   * 1: ``raise TOS`` (raise exception instance or type at ``TOS``)
+   * 2: ``raise TOS1 from TOS`` (raise exception instance or type at ``TOS1``
+     with ``__cause__`` set to ``TOS``)
 
 
 .. opcode:: CALL_FUNCTION (argc)