Try to improve the explanation of the "raise" statement and how its arguments

are interpreted.
This closes SF bug #532467.

2 files changed, 39 insertions, 33 deletions

diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex
index 1f8b237..f16dc8e 100644
--- a/Doc/ref/ref4.tex
+++ b/Doc/ref/ref4.tex
@@ -192,11 +192,10 @@ the \keyword{except} clause must reference the same class or a base
 class of it.
 
 When an exception is raised, an object (maybe \code{None}) is passed
-as the exception's ``parameter'' or ``value''; this object does not
-affect the selection of an exception handler, but is passed to the
-selected exception handler as additional information.  For class
-exceptions, this object must be an instance of the exception class
-being raised.
+as the exception's \emph{value}; this object does not affect the
+selection of an exception handler, but is passed to the selected
+exception handler as additional information.  For class exceptions,
+this object must be an instance of the exception class being raised.
 
 See also the description of the \keyword{try} statement in section
 \ref{try} and \keyword{raise} statement in section \ref{raise}.
diff --git a/Doc/ref/ref6.tex b/Doc/ref/ref6.tex
index 8ebce48..12261e2 100644
--- a/Doc/ref/ref6.tex
+++ b/Doc/ref/ref6.tex
@@ -507,37 +507,44 @@ from __future__ import generators
 \end{productionlist}
 
 If no expressions are present, \keyword{raise} re-raises the last
-expression that was raised in the current scope.
-
-Otherwise, \keyword{raise} evaluates its first expression, which must yield
-a string, class, or instance object.  If there is a second expression,
-this is evaluated, else \code{None} is substituted.  If the first
-expression is a class object, then the second expression may be an
-instance of that class or one of its derivatives, and then that
-instance is raised.  If the second expression is not such an instance,
-the given class is instantiated.  The argument list for the
-instantiation is determined as follows: if the second expression is a
-tuple, it is used as the argument list; if it is \code{None}, the
-argument list is empty; otherwise, the argument list consists of a
-single argument which is the second expression.  If the first
-expression is an instance object, the second expression must be
-\code{None}.
+expression that was active in the current scope.  If no exception has
+been active in the current scope, an exception is raised that
+indicates indicates that this is the error.
 \index{exception}
 \indexii{raising}{exception}
 
-If the first object is a string, it then raises the exception
-identified by the first object, with the second one (or \code{None})
-as its parameter.  If the first object is a class or instance,
-it raises the exception identified by the class of the instance
-determined in the previous step, with the instance as
-its parameter.
-
-If a third object is present, and it is not \code{None}, it should be
-a traceback object (see section~\ref{traceback}), and it is
-substituted instead of the current location as the place where the
-exception occurred.  This is useful to re-raise an exception
-transparently in an except clause.
-\obindex{traceback}
+Otherwise, \keyword{raise} evaluates the expressions to get three
+objects, using \code{None} as the value of omitted expressions.  The
+first two objects are used to determine the \emph{type} and
+\emph{value} of the exception.
+
+If the first object is an instance, the type of the exception is the
+class of the instance, the instance itself if the value, and the
+second object must be \code{None}.
+
+If the first object is a class, it becomes the type of the exception.
+The second object is used to determine the exception value: If it is
+an instance of the class, the instance becomes the exception value.
+If the second object is a tuple, it is used as the argument list for
+the class constructor; if it is \code{None}, an empty argument list is
+used, and any other object is treated as a single argument to the
+constructor.  The instance so created by calling the constructor is
+used as the exception value.
+
+If the first object is a string, the string object is the exception
+type, and the second object becomes the exception value.
+
+If a third object is present and not \code{None}, it must be a
+traceback\obindex{traceback} object (see section~\ref{traceback}), and
+it is substituted instead of the current location as the place where
+the exception occurred.  If the third object is present and not a
+traceback object or \code{None}, a \exception{TypeError} exception is
+raised.  The three-expression form of \keyword{raise} is useful to
+re-raise an exception transparently in an except clause, but
+\keyword{raise} with no expressions should be preferred if the
+exception to be re-raised was the most recently active exception in
+the current scope.
+
 
 
 \section{The \keyword{break} statement \label{break}}