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

[Pablo Galindo Salgado]

Pablo Galindo Salgado <pablogsal at gmail.com> added the comment:

Thank you, everyone, for expressing clearly your different opinions and concerns. Without disregarding any of the
arguments so far I want to make some further clarifications on some points and why I still think this is important.

> FWIW, I would rather not see the docs littered with "/".

Although I assume there is not the intention, there is absolutely no reason to be disrespectful to the people that
think otherwise. You can express the same idea without implying that the feature is "litter". The same thing applies
to "unfortunate implementation" in another of the sentences that was used.

> This is another step toward making what I see as an unfortunate implementation detail into formal semantics.

The feature has as much formal semantics as it is possible already: is an official part of the language.

One of the things the PEP makes a lot of emphasis is the current status of the feature and how users see the syntax
is precisely caused because of a lack of documentation, exposition and ultimately (and very important) because it was
not valid Python syntax. The fact that many people were thinking that is a typo in the documentation or "noise" is precisely
because of this and I think having it in the docs is crucial for discovery.

Regarding the usefulness of having the syntax for users: is exactly as useful as knowing that some arguments are keyword-only
and those are documented and we did not have any discussion about this. One can disagree and argue that the usefulness of the
feature, when some users consider implementing functions that use both syntaxes, is much different between positional-only and
keyword-only and that one solve more common problems that the other, but that is irrelevant for people reading the documentation:
the relevant thing is that they tell you the restrictions when calling an existing function. And at that point, it does not matter
how common something is or how common is fall into the error condition. Also, take into account that there is a serious difference
between teaching someone how to react to the syntax (you cannot use keyword parameters for these arguments), which is done almost
immediately, and teaching someone when they want to use the syntax themselves on their function. And I want to make clear that I
acknowledge that there is a cognitive burden because there are more cases to remember.

I think documenting the trailing "/" is especially important because now users will find very confusing the fact that functions
only document the "/" in some places. They may start to believe that a trailing "/" is illegal syntax or that the "/" at the end
is optional. This will lead to even more confusion IMHO. This will also perpetuate another thing that the PEP put a lot of focus
on solving, which is removing the dissonance between the signature that appears in the documentation, the one in the help() and docstrings
and the one that inspect.signature will return. Precisely failing to document all cases will make this even more confusing and will severely
alter and bias any feedback that users could provide about any related aspect.

It is possible that some users were thinking that the bare "*" for keyword-only arguments was a typo when it was introduced and maybe
they were thinking that the author meant "*args", but we can all agree that that was not a problem. I don't see why this syntax needs
to have special treatment regarding that. Another sentence of the ZEN of Python reads "Special cases aren't special enough to break the rules"
and the rules at to this point is that there were absolutely no restrictions regarding using new syntax or terminology in the documentation.

I understand the concerns and I take them into account, but for these reasons together with what other core devs are exposing, I think this
syntax should be included into the documentation (including trailing "/") as this was one core motivation for the PEP.

----------

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