# HG changeset patch
# Parent  ef1922baafb56f5e4ac5f9ec3bd29dee6e849d19
Issue #14911: Document generator.throw() as having 1- and 3-arg forms

diff -r ef1922baafb5 Doc/howto/functional.rst
--- a/Doc/howto/functional.rst	Fri Dec 04 02:40:30 2015 +0000
+++ b/Doc/howto/functional.rst	Fri Dec 04 03:40:27 2015 +0000
@@ -589,7 +589,7 @@
 In addition to :meth:`~generator.send`, there are two other methods on
 generators:
 
-* :meth:`throw(type, value=None, traceback=None) <generator.throw>` is used to
+* :meth:`throw(value) <generator.throw>` is used to
   raise an exception inside the generator; the exception is raised by the
   ``yield`` expression where the generator's execution is paused.
 
diff -r ef1922baafb5 Doc/reference/datamodel.rst
--- a/Doc/reference/datamodel.rst	Fri Dec 04 02:40:30 2015 +0000
+++ b/Doc/reference/datamodel.rst	Fri Dec 04 03:40:27 2015 +0000
@@ -2326,7 +2326,8 @@
    :exc:`StopIteration`, or other exception) is the same as when
    iterating over the :meth:`__await__` return value, described above.
 
-.. method:: coroutine.throw(type[, value[, traceback]])
+.. method:: coroutine.throw(value)
+            coroutine.throw(type[, value[, traceback]])
 
    Raises the specified exception in the coroutine.  This method delegates
    to the :meth:`~generator.throw` method of the iterator that caused
diff -r ef1922baafb5 Doc/reference/expressions.rst
--- a/Doc/reference/expressions.rst	Fri Dec 04 02:40:30 2015 +0000
+++ b/Doc/reference/expressions.rst	Fri Dec 04 03:40:27 2015 +0000
@@ -430,14 +430,27 @@
    could receive the value.
 
 
-.. method:: generator.throw(type[, value[, traceback]])
+.. method:: generator.throw(value)
+            generator.throw(type[, value[, traceback]])
 
-   Raises an exception of type ``type`` at the point where the generator was paused,
+   Raises an exception of at the point where the generator was paused,
    and returns the next value yielded by the generator function.  If the generator
    exits without yielding another value, a :exc:`StopIteration` exception is
    raised.  If the generator function does not catch the passed-in exception, or
    raises a different exception, then that exception propagates to the caller.
 
+   In typical use, this is called with a single exception instance similar to the
+   way the :keyword:`raise` keyword is used.
+
+   For backwards compatibility, however, the second signature is
+   supported, following a convention from older versions of Python.
+   The *type* argument should be an exception class, and *value*
+   should be an exception instance.  If *value* is not provided, the
+   *type* constructor is called to get an instance.  If *traceback*
+   is provided, it is set on the exception, otherwise any existing
+   :attr:`~BaseException.__traceback__` attribute stored in *value* may
+   be cleared.
+
 .. index:: exception: GeneratorExit
 
 
diff -r ef1922baafb5 Objects/genobject.c
--- a/Objects/genobject.c	Fri Dec 04 02:40:30 2015 +0000
+++ b/Objects/genobject.c	Fri Dec 04 03:40:27 2015 +0000
@@ -312,8 +312,11 @@
 
 
 PyDoc_STRVAR(throw_doc,
-"throw(typ[,val[,tb]]) -> raise exception in generator,\n\
-return next yielded value or raise StopIteration.");
+"throw(value)\n\
+throw(type[,value[,traceback]])\n\
+\n\
+Raise exception in generator; return next yielded value or raise\n\
+StopIteration.");
 
 static PyObject *
 gen_throw(PyGenObject *gen, PyObject *args)
@@ -818,8 +821,11 @@
 return next iterated value or raise StopIteration.");
 
 PyDoc_STRVAR(coro_throw_doc,
-"throw(typ[,val[,tb]]) -> raise exception in coroutine,\n\
-return next iterated value or raise StopIteration.");
+"throw(value)\n\
+throw(type[,value[,traceback]])\n\
+\n\
+Raise exception in coroutine; return next iterated value or raise\n\
+StopIteration.");
 
 PyDoc_STRVAR(coro_close_doc,
 "close() -> raise GeneratorExit inside coroutine.");