GeezerVison

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, like set(iterable=set()). It's also a lie: it's not an empty tuple by default (it's a C NULL), 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 pass None 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