René's URL Explorer Experiment

Title: gh-91485: Doc: Using Python syntax to document builtin Python functions. by JulienPalard · Pull Request #96579 · python/cpython · GitHub

Open Graph Title: gh-91485: Doc: Using Python syntax to document builtin Python functions. by JulienPalard · Pull Request #96579 · python/cpython

X Title: gh-91485: Doc: Using Python syntax to document builtin Python functions. by JulienPalard · Pull Request #96579 · python/cpython

Description: 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: gh-91485

Open Graph Description: 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...

X Description: 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 "b...

Opengraph URL: https://github.com/python/cpython/pull/96579

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width