I tried my idea at documenting Python functions using only Python syntax (avoiding manpages-like brackets to denote optional arguments), please tell me what you think.

It sometimes went "badly", like:

-.. class:: set([iterable])+.. class:: set(iterable=())

where I "had" to use an empty tuple because it would have looked very recursive to use a set here, likeset(iterable=set()). It's also a lie: it's not an empty tuple by default (it's a CNULL), but there's no practical difference for the reader.

Sometimes the change is more neutral, like in:

-.. awaitablefunction:: anext(async_iterator[, default])+.. awaitablefunction:: anext(async_iterator)+                       anext(async_iterator, default)

or:

-.. function:: max(iterable, *[, key, default])-              max(arg1, arg2, *args[, key])+.. function:: max(iterable, /, *, key=None)+              max(iterable, /, *, default, key=None)+              max(arg1, arg2, *args, key=None)

(where I'm happy to remove, *[, because it hurt my eyes.)

Sometimes it's good as it add information:

-.. class:: complex([real[, imag]])+.. class:: complex(real=0, imag=0)

Or make more explicit where it's OK to passNone and where it's not, like in:

-.. class:: super([type[, object-or-type]])+.. class:: super()+           super(type, object_or_type=None)

I bet you think « People should know this syntax, or learn it anyway », but I don't think so, I mean yes they will learn it anyway, but why forcing them to learn it at the same time as they learn basic Python functions? Learning one thing at a time is complicated enough.

Many are alone facing those pages and showing them:

complex(real=0, imag=0)

teach them how to implement default arguments in their own functions, and explicitly show them what happen when they don't give the values, while:

complex([real[, imag]])

don't.

• Issue:documentation for function arguments #91485