Support Receives section for generator.send(...) params #145
Conversation
fixes numpy#47 TODO: tests
jnothman
changed the title
|
Ping @Dreem-Devices, @tacaswell, @stefanv who commented on the original issue. |
doc/format.rst
Outdated
| @@ -250,13 +250,21 @@ The sections of a function's docstring are: | |||
| Support for the **Yields** section was added in `numpydoc | |||
| <https://github.com/numpy/numpydoc>`_ version 0.6. | |||
|
|
|||
| 7. **Other Parameters** | |||
| 7. **Sent** | |||
There was a problem hiding this comment.
I am a bit torn about the order of Yields and Sent. Putting Sent first feels more natural to the way you use send (in that the next value to come out probably depends on the value you sent in or you would not be bothering to send anything in!).
On the other hand it yields a non-trivial value before you can send in a non trivial value so it should stay in this order.
On the other other hand, you do send in None first to prime the generator (but that is not what is being documented in this block).
There was a problem hiding this comment.
I had thought the idiom was to use next initially, then .send later.
I think the discomfort is partially with the sense of the word "Sent", which connotes a departing aspect (perhaps because it is not agentive). "Receives", in contrast, seems to fit better after "Yields".
There was a problem hiding this comment.
Interesting, I had not seen that idiom. I like sending None as it special-cases the first round less, but that is neither here nor there for this discussion.
"The generator is sent ..." vs "The generator receives ..."
The first is odd because we drop the 'is' in the section title and the second is odd because it feel more passive.
There was a problem hiding this comment.
"receives" sounds more correct than "sent" in my head.
There was a problem hiding this comment.
I prefer "receives" as well. Another possibility I can think of is "accepts," but I don't think I like that as much as "receives".
|
I'm going to ping my co worker @danielballan who is much better at naming things than I am. |
jnothman
changed the title
|
LGTM. Needs a rebase. |
|
@jnothman want to rebase this? I think it can go into 0.9.0 |
numpydoc/tests/test_docscrape.py
Outdated
| @@ -216,6 +235,38 @@ def test_yields(): | |||
| assert desc[0].endswith(end) | |||
|
|
|||
|
|
|||
| def test_sent(): | |||
| section = doc_sent['Receives'] | |||
| assert_equal(len(section), 2) | |||
There was a problem hiding this comment.
CI isn't happy: NameError: global name 'assert_equal' is not defined
You can just change this to plain assert
There was a problem hiding this comment.
and some more of the same several lines below
fixes #47