bpo-23556: [doc] Fix inaccuracy in documentation for raise without args. Improve tests for context in nested except handlers. (GH-29236)

2 files changed, 18 insertions, 17 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index e093425..d0b2e62 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -38,15 +38,14 @@ information on defining exceptions is available in the Python Tutorial under
 Exception context
 -----------------
 
-When raising (or re-raising) an exception in an :keyword:`except` or
-:keyword:`finally` clause
-:attr:`__context__` is automatically set to the last exception caught; if the
-new exception is not handled the traceback that is eventually displayed will
-include the originating exception(s) and the final exception.
-
-When raising a new exception (rather than using a bare ``raise`` to re-raise
-the exception currently being handled), the implicit exception context can be
-supplemented with an explicit cause by using :keyword:`from<raise>` with
+When raising a new exception while another exception
+is already being handled, the new exception's
+:attr:`__context__` attribute is automatically set to the handled
+exception.  An exception may be handled when an :keyword:`except` or
+:keyword:`finally` clause, or a :keyword:`with` statement, is used.
+
+This implicit exception context can be
+supplemented with an explicit cause by using :keyword:`!from` with
 :keyword:`raise`::
 
    raise new_exc from original_exc
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 3d02074..e9795d8 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -563,10 +563,10 @@ The :keyword:`!raise` statement
 .. productionlist:: python-grammar
    raise_stmt: "raise" [`expression` ["from" `expression`]]
 
-If no expressions are present, :keyword:`raise` re-raises the last exception
-that was active in the current scope.  If no exception is active in the current
-scope, a :exc:`RuntimeError` exception is raised indicating that this is an
-error.
+If no expressions are present, :keyword:`raise` re-raises the
+exception that is currently being handled, which is also known as the *active exception*.
+If there isn't currently an active exception, a :exc:`RuntimeError` exception is raised
+indicating that this is an error.
 
 Otherwise, :keyword:`raise` evaluates the first expression as the exception
 object.  It must be either a subclass or an instance of :class:`BaseException`.
@@ -581,8 +581,8 @@ The :dfn:`type` of the exception is the exception instance's class, the
 A traceback object is normally created automatically when an exception is raised
 and attached to it as the :attr:`__traceback__` attribute, which is writable.
 You can create an exception and set your own traceback in one step using the
-:meth:`with_traceback` exception method (which returns the same exception
-instance, with its traceback set to its argument), like so::
+:meth:`~BaseException.with_traceback` exception method (which returns the
+same exception instance, with its traceback set to its argument), like so::
 
    raise Exception("foo occurred").with_traceback(tracebackobj)
 
@@ -614,8 +614,10 @@ exceptions will be printed::
      File "<stdin>", line 4, in <module>
    RuntimeError: Something bad happened
 
-A similar mechanism works implicitly if an exception is raised inside an
-exception handler or a :keyword:`finally` clause: the previous exception is then
+A similar mechanism works implicitly if a new exception is raised when
+an exception is already being handled.  An exception may be handled
+when an :keyword:`except` or :keyword:`finally` clause, or a
+:keyword:`with` statement, is used.  The previous exception is then
 attached as the new exception's :attr:`__context__` attribute::
 
    >>> try: