Paul Ganssle <p.gans...@gmail.com> added the comment:

> I respectfully disagree with logic, "the language now permits this, so we 
> should change all the docs to display it everywhere".  That moves it from 
> optional knowledge to mandatory knowledge, from a day ten lesson to a day one 
> lesson, from "once in a while, a user may benefit from being able to mark 
> arguments as positional-only" to the category of "every single user will see 
> this every time they see the docs".  There is a huge difference.

A decent part of the reasoning for the PEP was actually to create a standard 
way to document when arguments to a function are positional-only. By adopting 
the notation (already used in the numpy documentation IIRC), it makes a concise 
documentation clear.

Another part of the PEP's reasoning was that this notation is difficult to 
understand at least partially because it is rarely encountered, so "people 
don't understand it" as a reason to exclude it from the documentation becomes a 
bit of a self-fulfilling prophecy.

I am not really an expert in documentation and front-end design, but maybe it 
would be possible to have some sort of unobtrusive tooltip that activates on 
signatures that contain positional-only arguments?

----------
nosy: +p-ganssle

_______________________________________
Python tracker <rep...@bugs.python.org>
<https://bugs.python.org/issue37134>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

Reply via email to