[docs] [issue14911] generator.throw() documentation inaccurate

[Martin Panter]

Martin Panter added the comment:

I can’t really comment on the 2.7 version, because I’m not too familiar with Python 2 exceptions.

For Python 3, is there any reason to bless the None, tuple or non-exception cases as the exception “value” argument? IMO these just make things too complicated without any benefit. Changes I would make to the patch:

* Only mention that “value” can be omitted, or it can be an instance of the class specified by “type”. Drop mentioning the None option, and the single or tuple constructor argument options. It looks like the tuple option actually gets expanded to multiple constructor arguments?!
* Mention that if “value” is passed, its traceback could be lost
* Drop the example, unless someone can come up with a concise and realistic example
* Unify with definition for coroutines <https://docs.python.org/dev/reference/datamodel.html#coroutine.throw>
* Change the doc string(s) to match the argument names, but don’t bother copying the full definition text

----------
stage: needs patch -> patch review

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14911>
_______________________________________