Description

JulienPalard

opened on Oct 16, 2022

Issue body actions

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. ».

Reacted by Alex Waygood

Activity

1. JulienPalard

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Oct 16, 2022
2. rhettinger commented on Oct 17, 2022

   

   rhettinger

   on Oct 17, 2022

   Contributor

   More actions

   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.

   Reacted by Dave, Jeremy Kloth, andrei kulakov, Safihre and Wim Jeantine-Glenn
3. JulienPalard commented on Oct 17, 2022

   

   JulienPalard

   on Oct 17, 2022

   MemberAuthor

   More actions

   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.
4. slateny commented on Oct 17, 2022

   

   slateny

   on Oct 17, 2022

   Contributor

   More actions

   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.

   Reacted by Alex Waygood and Oleg Iarygin
5. rhettinger commented on Oct 18, 2022

   

   rhettinger

   on Oct 18, 2022

   Contributor

   More actions

   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]].
6. slateny commented on Oct 20, 2022

   

   slateny

   on Oct 20, 2022

   Contributor

   More actions

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

   closed this as completedin #99476on Nov 19, 2022
8. hauntsaninja

   added a commit that references this issue on Dec 27, 2022

   pythongh-100546: Remove incorrect positional-only marker from eval

   5f05995

Issue actions