[docs] [issue37134] [EASY] Use PEP570 syntax in the documentation

[Brett Cannon]

Brett Cannon <brett at python.org> added the comment:

FYI when Guido said "call on the steering council" I think he meant open an issue at https://github.com/python/steering-council/issues as this will get lost otherwise (i.e. Guido already removed himself from the nosy list so this already doesn't have the whole council participating).

Anyway, from my personal view, I think we should use the syntax. It's officially part of the language at this point and so avoiding it in the docs seems odd, like we're saying that we're ashamed of this syntax and you should pretend it doesn't exist when it does and it isn't going anywhere. Otherwise aren't we're forcing users to realize that the function definition in the docs deviates from what is definable in this one instance and that one has to read the full text to know that something is doable syntactically but we're leaving it out of the docs? It adds inconsistency in what the definition line means IMO based on how we have usually chosen to try and express things in that 'def' line in the docs as succinctly as possible to communicate the semantics of calling that function.

And I realize that Raymond's "unscientific twitter poll had mostly WTF reactions from end-users", but that's also sampling from people who have probably never used the syntax in real life or read docs regularly that use it. I've actually been wanting to use the syntax to say "the name isn't important here" as I've had to already close a PR that wanted to tweak documentation for name consistency where it actually didn't matter because the code used positional-only parameters but they weren't explicitly documented as such. Going back and saying "positional-only" to communicate that everywhere that it applies versus using the syntax we have to express that seems unnecessary to me.

Or put another way, how would you want to update:

len(obj)
        Return the number of items in a container.

to properly reflect the fact that *obj* is positional-only which is now an official concept in the language? We've been glazing over this for ages in the docs because we didn't have a way of expressing it succinctly and it only touched C-implemented code and we lacked a way to state it in Python, but now we have a way to state this fact. You could add a "The **obj** parameter is positional-only.", but to me that requires unnecessary reading of the text body if all I'm doing is checking the parameter order (and maybe the first sentence). And I realize we have gotten away with this until now, but as the concept of positional-only parameters grows that will become more of an issue.

Not using / also means that we're deviating from what help() emits, which could cause its own confusion as more people learn about the new syntax.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue37134>
_______________________________________