Use syntactically correct examples on abc package page

[greatvovan]

BPO	43698
Nosy	@corona10, @miss-islington, @greatvovan, @sobolevn
PRs	bpo-43698: do not use ... as argument name in docs #30502 [3.10] bpo-43698: do not use ... as argument name in docs (GH-30502) #30917 [3.9] bpo-43698: do not use ... as argument name in docs (GH-30502) #30918

^{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 = None
created_at = <Date 2021-04-01.18:18:39.308>
labels = ['type-bug', '3.8', '3.9', '3.10', 'docs']
title = 'Use syntactically correct examples on abc package page'
updated_at = <Date 2022-01-26.12:42:42.831>
user = 'https://github.com/greatvovan'

bugs.python.org fields:

activity = <Date 2022-01-26.12:42:42.831>
actor = 'miss-islington'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-04-01.18:18:39.308>
creator = 'Vladimir Ryabtsev'
dependencies = []
files = []
hgrepos = []
issue_num = 43698
keywords = ['patch']
message_count = 5.0
messages = ['390004', '410157', '411727', '411746', '411747']
nosy_count = 5.0
nosy_names = ['docs@python', 'corona10', 'miss-islington', 'Vladimir Ryabtsev', 'sobolevn']
pr_nums = ['30502', '30917', '30918']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue43698'
versions = ['Python 3.8', 'Python 3.9', 'Python 3.10']

Linked PRs

• gh-87864: Use correct function definition syntax in the docs #103312
• [3.11] gh-87864: Use correct function definition syntax in the docs (GH-103312) #103442

[greatvovan]

There are code snippets on the package's page (https://docs.python.org/3.10/library/abc.html) like this:

class C(ABC):
    @classmethod
    @abstractmethod
    def my_abstract_classmethod(cls, ...):
        ...

Here, the author probably wanted to demonstrate that the method may have any other arguments in addition to cls, but it makes the code not compilable:

    def my_abstract_classmethod(cls, ...):
                                     ^
SyntaxError: invalid syntax

Additionally it uses the same Ellipsis as in the method's body (that is supposed to indicate a stub), which is confusing.

I think that all code samples must be syntactically correct, so that if a reader copypastes them into their code editor they would work right away. I suggest to remove ellipsis in the argument lists everywhere on the page and replace them with one of the following:

• sample parameters such as a, b, c or my_arg1, my_arg2,
• *args, **kwargs,
• nothing.

[sobolevn]

Thank you, I fully agree that this can be improved.

Please, take a look at #30502
I will apprecaite your review!

[corona10]

New changeset b9d8980 by Nikita Sobolev in branch 'main':
bpo-43698: do not use ... as argument name in docs (GH-30502)
b9d8980

[miss-islington]

New changeset a57ec7a by Miss Islington (bot) in branch '3.10':
bpo-43698: do not use ... as argument name in docs (GH-30502)
a57ec7a

[miss-islington]

New changeset 49971b2 by Miss Islington (bot) in branch '3.9':
bpo-43698: do not use ... as argument name in docs (GH-30502)
49971b2

[slateny]

I think this (docs) needs to be changed as well

[sobolevn]

(misclick, sorry)

@slateny yes, good catch. I will send a PR.

[sobolevn]

Fixed!

Please, open new issues for any leftovers :)