[issue14878] send statement from PEP342 is poorly documented.
New submission from Stephen Lacy <slacy@slacy.com>: There's reasonable documentation of the yield statement for most python versions under Section 6: Simple Statements, particularly 6.8 "The Yield Statement" (http://docs.python.org/release/2.7/reference/simple_stmts.html#the-yield-sta...) But, there's no mention of the return value of the yield statement, or that the send statement even exists. It's mentioned in passing here under "PEP342 New Generator Features" (http://docs.python.org/whatsnew/2.5.html#pep-342-new-generator-features) but should be given fuller explanation and cross-linking from the yield statement documentation. It's also mentioned a bit here: http://docs.python.org/howto/functional.html#passing-values-into-a-generator but again, not under the language documentation itself. ---------- assignee: docs@python components: Documentation messages: 161320 nosy: Stephen.Lacy, docs@python priority: normal severity: normal status: open title: send statement from PEP342 is poorly documented. versions: Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
Stephen Lacy <slacy@slacy.com> added the comment: okay, found the documentation I was looking for here: http://docs.python.org/reference/expressions.html#yield-expressions which appears to be copied and pasted and modified version of the docs here: http://docs.python.org/reference/simple_stmts.html#grammar-token-yield_stmt At the very least these should cross-reference each other, but I would guess that the text should be unified, but I'm not sure where. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Thanks for the report. Are you interested in making a patch? Guidelines are in the devguide. ---------- nosy: +eric.araujo stage: -> needs patch title: send statement from PEP342 is poorly documented. -> Improve documentation for generator.send method versions: -Python 2.6, Python 3.1, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
Jan Duzinkiewicz added the comment: The latest docs have a crossrefence at the end of the section: http://docs.python.org/3/reference/simple_stmts.html#grammar-token-yield_stm... I copied the reference to 2.7 docs ---------- keywords: +patch nosy: +dhgmgn Added file: http://bugs.python.org/file27842/14878.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
Roundup Robot added the comment: New changeset 7b8c0bf8fcb8 by Andrew Kuchling in branch '2.7': #14878: add cross-reference to the yield statement. http://hg.python.org/cpython/rev/7b8c0bf8fcb8 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
A.M. Kuchling added the comment: Thanks for the patch! ---------- nosy: +akuchling resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- stage: needs patch -> committed/rejected type: -> enhancement versions: -Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue14878> _______________________________________
participants (6)
-
A.M. Kuchling -
Ezio Melotti
-
Jan Duzinkiewicz
-
Roundup Robot
-
Stephen Lacy
-
Éric Araujo