classification
Title: Improve documentation for generator.send method
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Stephen.Lacy, akuchling, dhgmgn, docs@python, eric.araujo, python-dev
Priority: normal Keywords: patch

Created on 2012-05-22 04:54 by Stephen.Lacy, last changed 2013-05-10 01:19 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
14878.patch dhgmgn, 2012-11-02 11:33 review
Messages (6)
msg161320 - (view) Author: Stephen Lacy (Stephen.Lacy) Date: 2012-05-22 04:54
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-statement)

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.
msg161364 - (view) Author: Stephen Lacy (Stephen.Lacy) Date: 2012-05-22 16:39
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.
msg161598 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2012-05-25 18:49
Thanks for the report.  Are you interested in making a patch?  Guidelines are in the devguide.
msg174503 - (view) Author: Jan Duzinkiewicz (dhgmgn) Date: 2012-11-02 11:33
The latest docs have a crossrefence at the end of the section:

http://docs.python.org/3/reference/simple_stmts.html#grammar-token-yield_stmt

I copied  the reference to 2.7 docs
msg188800 - (view) Author: Roundup Robot (python-dev) Date: 2013-05-10 00:55
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
msg188801 - (view) Author: A.M. Kuchling (akuchling) * (Python committer) Date: 2013-05-10 00:56
Thanks for the patch!
History
Date User Action Args
2013-05-10 01:19:45ezio.melottisetstage: needs patch -> resolved
type: enhancement
versions: - Python 3.2, Python 3.3
2013-05-10 00:56:12akuchlingsetstatus: open -> closed

nosy: + akuchling
messages: + msg188801

resolution: fixed
2013-05-10 00:55:46python-devsetnosy: + python-dev
messages: + msg188800
2012-11-02 11:33:06dhgmgnsetfiles: + 14878.patch

nosy: + dhgmgn
messages: + msg174503

keywords: + patch
2012-05-25 18:49:18eric.araujosetnosy: + eric.araujo
title: send statement from PEP342 is poorly documented. -> Improve documentation for generator.send method
messages: + msg161598

versions: - Python 2.6, Python 3.1, Python 3.4
stage: needs patch
2012-05-22 16:39:07Stephen.Lacysetmessages: + msg161364
2012-05-22 04:54:52Stephen.Lacycreate