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 :-)