gh-144837: Improve documentation for more collection methods#144841
gh-144837: Improve documentation for more collection methods#144841serhiy-storchaka merged 4 commits intopython:mainfrom
Conversation
Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation.
| .. method:: append(value, /) | ||
|
|
||
| Append a new item with value *x* to the end of the array. | ||
| Append a new item with the specified value to the end of the array. |
There was a problem hiding this comment.
| Append a new item with the specified value to the end of the array. | |
| Append a new item with the specified *value* to the end of the array. |
There was a problem hiding this comment.
Not sure about this. I tried to avoid value *value*.
|
|
||
|
|
||
| .. method:: list.index(x[, start[, end]]) | ||
| .. method:: list.index(value[, start[, stop]) |
There was a problem hiding this comment.
This still has square brackets? Also, they are unbalanced.
There was a problem hiding this comment.
Good catch! I copied it from other place which already had such error.
As for the signature of the index() methods, this is a different issue. First, we need to decide if it needs to support None (see #138134), or this is just an unintentional implementation artifact. If yes, then we can write
list.index(value, start=None, stop=None, /)
If not, then we need to write
list.index(value, start=0, stop=sys.maxsize, /)
or use multiple signatures:
list.index(value, start=0, /)
list.index(value, start, stop, /)
This is a separate large issue.
|
When you're done making the requested changes, leave the comment: |
Co-authored-by: Ned Batchelder <ned@nedbatchelder.com>
serhiy-storchaka
left a comment
serhiy-storchaka
left a comment
There was a problem hiding this comment.
I have made the requested changes; please review again.
|
|
||
|
|
||
| .. method:: list.index(x[, start[, end]]) | ||
| .. method:: list.index(value[, start[, stop]) |
There was a problem hiding this comment.
Good catch! I copied it from other place which already had such error.
As for the signature of the index() methods, this is a different issue. First, we need to decide if it needs to support None (see #138134), or this is just an unintentional implementation artifact. If yes, then we can write
list.index(value, start=None, stop=None, /)
If not, then we need to write
list.index(value, start=0, stop=sys.maxsize, /)
or use multiple signatures:
list.index(value, start=0, /)
list.index(value, start, stop, /)
This is a separate large issue.
serhiy-storchaka
force-pushed
the
docs-collections-signatures
branch
from
7ac12f6 to
e0fe9c7
Compare
|
I'll merge this, and then, as we discussed at https://discuss.python.org/t/a-small-typo-on-5-1-more-on-lists-section/106150, we will try to improve the section in the tutorial. |
|
Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14. |
…ythonGH-144841) Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation. (cherry picked from commit 17070f4) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
…ythonGH-144841) Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation. (cherry picked from commit 17070f4) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
|
GH-146483 is a backport of this pull request to the 3.14 branch. |
|
GH-146484 is a backport of this pull request to the 3.13 branch. |
…ythonGH-144841) Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation.
3 participants
Use uniform standard signature syntax in the tutorial and in the array and collections modules documentation.
📚 Documentation preview 📚: https://cpython-previews--144841.org.readthedocs.build/