The Python Documentation Editorial Board is continuing to pilot our processes for working together. Our decisions will largely be recorded as changes to the Documentation section of the devguide.
In this case I would rather support your decision (on the ground “reference material should prioritize precision and completeness”), but I’m little surprised why this case wasn’t discussed outside of PDEB. Last time I was trying to push a patch in this direction - it was rejected with a message “There was a decision not to add these to the docs because lay readers mostly find them confusing, because it makes the docs harder to read”.
While I was asked several times something along “why help() and sphinx docs show different function signatures?”, I trust @rhettinger teaching experience that such verbose syntax might be confusing.
In this case, we felt the decision was clear: reference material should be precise. Without the punctuation, important details about the function were missing, or had to be expressed in English.
We understand the punctuation is terse and might be unfamiliar. We’d like to explore ways to help new learners understand them in context.
The Editorial Board is still fairly new. We’ll adjust processes based on feedback, of course.
In this case, I’d appreciate if the PR explicitly said that the EB did read and consider previous discussions, in particular #81315, #98340 and SC#12, and still decided the way they did, extending/overriding the previous decision.
It could be helpful to auto-tag with <abbr></abbr> tags:
func1(a, b, <abbr title="Parameters before the slash (/) are positional-only.">/</abbr>)
> func2(<abbr title="Parameters following the star (*) are keyword-only.">*</abbr>, kwarg1, kwarg2)
Rendered:
func1(a, b, /)
func2(*, kwarg1, kwarg2)
*args and **kwargs could also be tagged, although those are more likely to be addressed in the body of the docstring.
I have no idea how helpful/annoying large numbers of <abbr></abbr> tags are for screenreader users, but I find the dotted underline is the right level of ignorable-at-will for things like this that are helpful to have at hand until the shorthand becomes familiar.
This device test from January says screen readers mostly do not announce <abbr title=>s, except for Android/Chrome/Talkback that only announces the title, and then a couple that might when using virtual cursor.
The title is also not exposed in Braille displays, and can’t be accessed by keyboard or touchscreen (for example, mobile phone) users.
Don’t use <abbr> with or without title. Exposure continues to be inconsistent across browsers and assistive technologies. Some set of users will always miss some piece of information.
I never much liked the previous decision to sometimes leave signatures intentionally incomplete, thus allowing continued questions when users violate the hidden restriction, and discouraging users from using call options when available (because of uncertainty). +1 from me.
When / first appeared in inspect.signature returns for C functions, I added a note in IDLE tooltips to explain. When they because legal in Python code, I removed them since people needed to learn the option anyway. The referenced ‘previous decision’ said it “can then be revisited for Python 3.9.” We are well past that.