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

[Pablo Galindo Salgado]

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

Thank you, Raymond, for sharing your concerns regarding this. I am sorry you disagree with this change.

I would want to expose the reasons I think this is important and justified, but please, don't read this
as a way of dismissing your concerns; I really respect your opinion and judgment (as an example, I am waiting
until you are happy with the API in issue17005 even if that meant waiting 2 years until the next release).

1) The docstrings for these functions already show the "/". As Matthias Bussonnier from IPython and Jupyter has expressed
multiple times, there are a ton of users that do not read html documentation and rely solely on the output from help (either
in Jupyter, IPython or CPython). These users find very strange that the signatures of the docstrings differ when they actually
check the html docs. Some examples of the docstrings:

>>> help(zlib.decompress)
    decompress(data, /, wbits=15, bufsize=16384)
    Returns a bytes object containing the uncompressed data.

>> help(codecs.register)
register(search_function, /)
    Register a codec search function.

2) This communicates the users more explicitly how to call the function and what to expect when this happens,
which is the purpose of documenting signatures in the documentation. We are already documenting keyword-only
parameters for the same reasons.

3) This PR is not changing any of the signatures, is just documenting and informing users what the signature is
and how it will behave. Is just expressing information. The documentation must be user-friendly, but also needs to
be technical.

4) We are already documenting positional-only arguments in multiple other functions in the documentation. This PR just
continues doing that. Some examples of the many cases:

https://docs.python.org/3.8/library/functools.html#functools.partialmethod
https://docs.python.org/3.8/library/threading.html#threading.excepthook
https://docs.python.org/3.8/library/inspect.html#inspect.getcallargs
...

5) I give training sessions to different levels (people that are starting to program, Juniors and Seniors) and they are always
confused when the signature of the function in the documentation does not match the docstring or the actual way of calling the function.
This also includes when we use constructs like f(x, ...), f(x, [y=None,]), f(K) -> V or similar because they are not valid Python
signatures and they do not appear elsewhere. In general, my experience is that people want the signature documented as close as possible
to the real signature in the technical documentation.

I wished we could have iterate over this together having a good discussion before involving the steering council, and I am sorry
if you were afraid that your concerns would have not been listened to. Sadly, I have not answered before because it was 1:26 in the morning
here when you posted your message. I have left the PR open and opened an issue because is the normal workflow and because this allows people
to express here their opinion. 

I think this change is important, but I also think of working together and respecting and understanding everyone's point of view
is much more important. If you think me pushing for this change will impact somehow our ability to work together I will close the PR
and the issue.

For now, I won't do anything before the steering council decides what to do.

I apologize to everyone or the wall of text.

----------

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