Improve documentation for generator.send method

[StephenLacy]

BPO	14878
Nosy	@akuchling, @merwok
Files	14878.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2013-05-10.00:56:12.853>
created_at = <Date 2012-05-22.04:54:52.410>
labels = ['type-feature', 'docs']
title = 'Improve documentation for generator.send method'
updated_at = <Date 2013-05-10.01:19:45.907>
user = 'https://bugs.python.org/StephenLacy'

bugs.python.org fields:

activity = <Date 2013-05-10.01:19:45.907>
actor = 'ezio.melotti'
assignee = 'docs@python'
closed = True
closed_date = <Date 2013-05-10.00:56:12.853>
closer = 'akuchling'
components = ['Documentation']
creation = <Date 2012-05-22.04:54:52.410>
creator = 'Stephen.Lacy'
dependencies = []
files = ['27842']
hgrepos = []
issue_num = 14878
keywords = ['patch']
message_count = 6.0
messages = ['161320', '161364', '161598', '174503', '188800', '188801']
nosy_count = 6.0
nosy_names = ['akuchling', 'eric.araujo', 'docs@python', 'python-dev', 'Stephen.Lacy', 'dhgmgn']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue14878'
versions = ['Python 2.7']

[StephenLacy]

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 "PEP-342 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.

[StephenLacy]

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.

[merwok]

Thanks for the report. Are you interested in making a patch? Guidelines are in the devguide.

[dhgmgn]

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

[python-dev]

New changeset 7b8c0bf8fcb8 by Andrew Kuchling in branch '2.7':
bpo-14878: add cross-reference to the yield statement.
http://hg.python.org/cpython/rev/7b8c0bf8fcb8

[akuchling]

Thanks for the patch!