STINNER Victor <vstin...@redhat.com> added the comment:
Tim Peters: "I haven't looked at anything in this PR, so just popping in to confirm that the first time I saw stuff like: len(obj, /) in the docs I had no idea at all what it was trying to say. I thought it was a typo. (...)" Carol Willing: "I confess that I had a similar reaction as Tim when I saw functions with a trailing `/`." I'm quite sure that many users have same reaction the first time they meet "@decorator", "*args", "def func(*, arg)", etc. PEP 570 introduces a syntax which was still illegal in Python 3.7, so it's normal to be surprised when we meet a new syntax. In a few years, people will be used to that, but will be surprised by yet another new syntax ;-) The best we can do is to enhance the documentation to properly document "/", directly in the reference documentation. Sphinx is a great help to add links. And we can maybe extend Sphinx to add even more inline hints. -- The "/" character was discussed in length in the PEP 570. Many people complained... but nobody succeed to came up with a better syntax. The PEP has been accepted and its now part of the *Python language*. As explained in length in the PEP 570, the "/" syntax is *not* new. For example, it is used for years in Python docstrings. Paul Ganssle also mentioned that this notation is "already used in the numpy documentation IIRC". -- I don't think that we must hide some syntax like "*args" or "def func(*, arg)" from the doc, just because people learning Python might be surprised at the first read. I don't think that the reference documentation should be used to learn Python. They are way better resources than that to learn Python. Moreover, it's not really written like a tutorial. We have some https://docs.python.org/dev/howto/ for that. >From my point of view, the *reference* documentation is more used by people >who are already used to Python and so know the Python syntax. Trying to hide >the real API in the *reference* documentation sounds weird (wrong) to me. The >doc should document the real behavior. The PEP 570 makes is possible, whereas >previously, the doc was lying. If you consider that "len(obj, /)" is a typo, maybe we must fix len to accept obj as a keyword parameter? But they are good reasons why it's a positional only parameter. I don't think that anyone wants to change that. The current trend is more the opposite: convert some positional-or-keyword parameters to positional-only parameters, especially for functions taking a single parameter. In short, I concur with Brett who wrote: > 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. -- By the way, PR 13743 doesn't modify every single function of the documentation. Only a few files are modified, simply because only few functions accept positional-only parameters. My expectation is more that nobody will notice :-) ---------- keywords: -easy nosy: +serhiy.storchaka _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue37134> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
