Document when to use positional-only markers

[hauntsaninja]

This was recently the source of confusion that led to a sequence of PRs and reverts that caused a documentation regression, e.g. see python/cpython#100546 python/cpython#98340 python/cpython#91485 and some of the related PRs.

python/cpython#100444 (comment) is a reasonable summary of the current policy.

(Acknowledging there are somewhat related larger discussions, like how to document default values, when to use [] for optional parameters, whether to include types in documentation, but we can document the status quo before we figure those out. If we come up with some really nice solution for types in documentation, that could be a good place for positional-only information to live)

[CAM-Gerlach]

@ezio-melotti @erlend-aasland you'll likely be interested in this as well...

Great point. As far as has been presented, the status quo is that there apparently is no clear policy, guidance or consensus on when to use the standard positional-only markers vs. more esoteric/contrived syntax, just individual dev's opinions, as is presented in that comment—and at least in the issues/PRs listed, I couldn't really find any others actively advocating for the same particular position.

As such, before enshrining any particular opinion as concrete written guidance in the devguide, IMO it would be a lot more beneficial to have a public discussion on this issue first (specifically, use of / vs. [ in signatures, and perhaps also including default values if we define the topic more broadly to be having function signature syntax follow the standard, expected Python convention to the extent practical), on Discourse and perhaps also at the monthly docs community (and editorial board) meeting, and document the resulting consensus.

FWIW, in the interests of full disclosure, my current viewpoint is that while it may be worth considering special-casing functions.rst for now for the reasons mentioned, and I do agree that improvements should be considered and made holistically and targeting toward the more complex functions where they are of the most benefit first, in general clarity, consistency, precision and lack of any ambiguity are critical attributes of API reference documentation. I do think they should be made as accessible as is practical to beginners, but I believe that can be done by other means* that don't significantly compromise the overriding goal of reference documentation: to describe, and to do that clearly, accurately and comprehensively.

* IMO, instead of special-casing functions.rst (or other areas), it should be possible to use a Sphinx extension to link the / and * in function signatures to a glossary entry or other basic, accessible explanation of what it means to mitigate the concern about confusing users without sacrificing clarity, precision and consistency in the Reference.

[willingc]

It looks as if this has been added to cpython docs. Closing here since it is out of scope for the devguide.

[AlexWaygood]

@willingc are you sure this has been addressed in CPython? I think deciding on a general policy here, and adding it to the devguide, would be really useful. python/cpython#91485 didn't decide on a general policy here; somebody just happened to mention this issue in a comment as part of that PR thread :)

[merwok]

FTR this was discussed again by the docs editorial board.

[AlexWaygood]

Fixed in #1344 by @nedbat