[idea] Ease understanding of positional-only and keyword-only makers in function prototyes

[JulienPalard]

Documentation

In https://docs.python.org/dev/library/functions.html I added many / and * markers in function prototypes. There were already a few of them here, and I bet there is some in other places in the doc too.

For newcomers it may look like a typo, and it may be hard for them to discover what it means.

I think it would be nice to tell them what it is, maybe by making all markers a link to the glossary or by displaying a message on mouse hover like « The parameters on the left of a / are positional-only. ».

[rhettinger]

I thought we had decided long ago to not use these markers unless there was a specific need. It has the effect of makes the docs much less usable without the benefit of having a trainer. AFAICT, no other language docs have this sort of notion, so Python is the outlier.

A hover-over is insufficient. In my experience doing training with experienced engineers, it is common for a person's mind to initially rebel at the notion until given a full explanation of the benefits of adding the restrictions.

This notation is barrier for users just trying to read the docs to lookup a function. Almost no one benefits from the notation. If a person is looking up len(), it is baffling to see len(obj, /. All they really needed was to know that len("hello") was how you write the function.

Also note that in the many beginner tutorials seen around the web (either written or video), almost none mention * and /. The Python docs need to be more accessible rather than less. A lot of people learn Python on their own and this is an obstacle for them.

This notation was important to us as experienced developers to give us finer grained control over input patterns and to be able to match a C function more exactly. For almost everyone else, the notation is of zero value and just gets in the way of reading the docs. People can happily program in Python for years without knowing the argument restriction notation. Let's not get in the way of that happiness. Python should remain a beginner friendly language.

I recommend reverting the change to the functions.html. We had previously agree not to sweep through the docs and apply the positional-only and keyword-only notation. It wasn't an oversight.

[JulienPalard]

I thought we had decided long ago

Is it documented? I've never heard of it and I see good usages of those markers already in the doc.

For the rest, I agree.

My initial goal was to avoid hard-to-read things like bytearray([source[, encoding[, errors]]]) in the functions.html page, and after reviews the PR derived to this overzealous state, and should have needed a discussion beforehand.

[slateny]

If we do decide not to keep the position/keyword markers, could we still somehow keep documentation of the default arguments? I think those are useful and even a beginner can make reasonable assumptions or ignore what it is since it's more intuitive than the markers.

[rhettinger]

Check with Carol. She was party to the decision to not sweep through the docs applying the new notation. I don't know where that decision was written down. It is likely in the same place as the decision to not put type annotations in the docs: enumerate(iterable: Iterable[_T], n: int=0) -> Iterator[tuple[int, _T]].

[slateny]

@willingc Would you happen to know whether the discussion on this was documented somewhere?