gh-100989: Fix docstrings of collections.deque

[timobrembeck]

See gh-100989 for the issue description.

Thanks in advance for your feedback!

[bedevere-bot]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

[cpython-cla-bot]

All commit authors signed the Contributor License Agreement.

[timobrembeck]

Most changes to Python require a NEWS entry.

Please add it using the blurb_it web app or the blurb command-line tool.

In my opinion, it doesn't, but let me know if you think the bot is right.

[CAM-Gerlach]

Standard reminder: You can directly apply all the suggestions you want in one go with Files changed -> Add to batch -> Commit

This change seems to have value overall, as it not only fixes the downstream Sphinx warnings, but is clearer and more explicit as well as more concise and consistent as to the parameter and return types of these methods (per Diataxis for reference docs), and provides much clearer and more detailed descriptions that fill in key missing details as to what the parameters actually do.

I did have a couple minor suggestions, see comments. Also, it would be good for someone familiar with both the docs and the C-API (like @erlend-aasland ) should probably also take a look at it. Thanks!

[CAM-Gerlach]

LGTM from my side from one trivial fix to my own typo. Thanks!

[erlend-aasland]

Seeing that Raymond (the code owner) specifically requested only the integer => int change to be applied, I think it would better to reduce this PR to that specific change only.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[timobrembeck]

Seeing that Raymond (the code owner) specifically requested only the integer => int change to be applied, I think it would better to reduce this PR to that specific change only.

@erlend-aasland Thanks a lot for your thoughts on this. As explained in #100989 (comment), this suggested change would not solve the Sphinx warning, since Sphinx does not recognize the -- pattern as separation of type and description. I would open a ticket on Sphinx' side if this code style is somehow a defined standard other projects should respect, but I did not find any resources on this. Do you know more about this, or in general a guideline docstrings should follow?

The smallest possible changes that would resolve the warning would be to also replace -- by two new lines, do you think this would be justified as well?

I still think that if the documentation of PyDoc_STRVAR tells us that we should write the docstrings according to PEP-7, we should do one of two things:

1. Actually write the docstrings according to that guideline
2. Or remove that passage from the docs and either require a (newer?) guideline or state that docstrings don't have to follow any specific formatting (in which case I would suggest that we also don't use the signature-like format function(params) -> return type (but not really), because it makes other tools like e.g. Sphinx' autodoc_docstring_signature think it's a machine parsable format, which it is not in that case).

[erlend-aasland]

@timoludwig: thanks for the explanation! I'll review it with this in mind.

[CAM-Gerlach]

And just to note, the eventual changes are AFAIK substantially modified and refined from those that the core dev in question initially was hesitant about on first glance. IMO, the much greater value here is not the specific Sphinx or formatting issue, but rather the substantial increase in clarity, consistency and completeness per the Diatxis guidelines for API reference documentation, particularly for the target audience users who may not be experts in the usage of the code in question.

[miss-islington]

Thanks @timoludwig for the PR, and @erlend-aasland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.10, 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-102910 is a backport of this pull request to the 3.11 branch.

[bedevere-bot]

GH-102911 is a backport of this pull request to the 3.10 branch.