[docs] [issue13386] Document documentation conventions for optional args

Baptiste Carvello report at bugs.python.org
Fri Nov 18 08:11:43 CET 2011

Baptiste Carvello <devel at baptiste-carvello.net> added the comment:

Le 18/11/2011 05:29, Terry J. Reedy a écrit :
> In the following, I give objections to this PO (position only) rule and suggest an alternative ND (no default) rule: use 'name=default' when there is a default and '[name]' when there is not'.
> The issue of whether an argument is required or optional is orthogonal to whether it can be passed by both position and name, only by name, or only by position.

With this logic, you would need to use '[name=default]' when an argument
is optional *and* can be passed by name.

Sure, this notation is inherently redundant, but is has the advantage of
conveying both informations immediately to the user. It is also more
coherent with '[name]'.

But this is a big change from the current philosophy...


Python tracker <report at bugs.python.org>

More information about the docs mailing list