bpo-36144: Document PEP 584. #18659
bpo-36144: Document PEP 584. #18659
Conversation
Doc/library/stdtypes.rst
Outdated
| @@ -4392,6 +4392,22 @@ pairs within braces, for example: ``{'jack': 4098, 'sjoerd': 4127}`` or ``{4098: | |||
| >>> d.values() == d.values() | |||
| False | |||
|
|
|||
| .. method:: d | other | |||
There was a problem hiding this comment.
Maybe use ‘describe’ instead of‘method’. (What do the docs for ‘set’ use?)
There was a problem hiding this comment.
set uses method, but it lists both the method and operator together. I agree that describe is probably better here.
Doc/whatsnew/3.9.rst
Outdated
| Merge (``|``) and update (``|=``) operators have been added to the built-in | ||
| :class:`dict` class. | ||
|
|
||
| .. XXX The rest is just a copy-paste of the PEP's Specification section. |
There was a problem hiding this comment.
Maybe drop the rest and link to the PEP instead? The comment above praises brevity. :-)
There was a problem hiding this comment.
I think the brevity bit is about the summary section, no? I latched onto "Do not spend very much time on the wording of your changes"... hence, the copy-paste. But you're right that it probably does not add much here.
Doc/whatsnew/3.9.rst
Outdated
| Merge (``|``) and update (``|=``) operators have been added to the built-in | ||
| :class:`dict` class. | ||
|
|
||
| .. XXX https://www.python.org/dev/peps/pep-0584/ |
There was a problem hiding this comment.
I'm not sure why you would want to keep a full link to the PEP in a comment. Do other sections do this?
There was a problem hiding this comment.
I misunderstood your prior review comment!
Doc/whatsnew/3.9.rst
Outdated
| Merge (``|``) and update (``|=``) operators have been added to the built-in | ||
| :class:`dict` class. | ||
|
|
||
| .. XXX https://www.python.org/dev/peps/pep-0584/ | ||
|
|
||
| See :pep:`584` for a full description. | ||
|
|
||
| (Contributed by Brandt Bucher in :issue:`36144`.) |
There was a problem hiding this comment.
Hm, looking at the rendered docs, and comparing other sections, I wonder if this shouldn't just be a single paragraph.
|
@gvanrossum I'm a bit confused. Looking at the "New Features" section of the What's New for 3.8, I see somewhat detailed docs with examples spread across several paragraphs (for example, for assignment expressions and positional-only parameters). The smaller, non-PEP items below are more compact though. However, I'm probably overthinking this, which is exactly what the comments at the top warn against. 🙂 I'll just keep the short version and the notes in one paragraph, as you suggest, and Łukasz or whoever will go back later and expand as needed, then? |
|
I'll land it now. If you feel regrets later (or someone else thinks the whatsnew section on dict|dict should have more information), just submit a PR with a doc update, referencing the same issue (https://bugs.python.org/issue36144). |
https://bugs.python.org/issue36144