[issue21314] Document '/' in signatures

[Nick Coghlan]

Nick Coghlan <ncoghlan at gmail.com> added the comment:

I went ahead and merged Lysandros's new FAQ entry (Thank you Lysandros!), as having some level of documentation for this notation is markedly better than the previous "none at all", and the PR added cross-references from the builtins and inspect module docs in addition to adding the FAQ itself.

However, I'm not closing the issue yet as:

- the exact wording could likely stand to be tweaked a bit (in particular, I'm not sure it's a good idea to reference PEP 570 from the FAQ entry)

- we may want to enhance pydoc itself to explain the notation inline (e.g. by appending a footer saying "Note: parameters to the left of ``/`` entries are positional only and cannot be passed by name" after the docstring being displayed when positional only parameters are found, and "Note: parameters to the right of ``*`` and ``*name`` entries are keyword only and can only be passed by name" when keyword only parameters are found)

- we may want to file a follow-up issue proposing that `pydoc` go back to either not marking positional-only parameters at all, or marking them differently (e.g. with "Note: *x*, *y*, and *z* are positional only parameters that cannot be passed by name" after the individual callable docstrings)

----------
nosy: +rhettinger -miss-islington
stage: patch review -> commit review

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue21314>
_______________________________________