Steven D'Aprano <st...@pearwood.info> writes:
> The full signature is:
>
> edir([object [, glob=''] [, dunders=True] [, meta=False]])
>
> All four arguments are optional, and dunders and meta are
> keyword-only.
The official documentation seems to prefer this style::
edit(object, glob='', *, dunders=True, meta=False)
(I think that's the style, anyway.)
I like that it gets rid of square brackets; with the notation showing a
default value, that already communicates that a parameter is optional.
Since the introduction of keyword-only arguments in Python functions,
the question arises of how to communicate this in documentation.
The lone asterisk showing the separation of keyword-only arguments from
the rest is confusing to me. Not least because it is (if I understand
correctly) invalid syntax to actually have that in Python code.
What are your thoughts, dear reader, on the documentation style for
showing a Python function signature, now that we have not only default
arguments but also keyword-only arguments?
--
\ “It is difficult to get a man to understand something when his |
`\ salary depends upon his not understanding it.” —Upton Sinclair, |
_o__) 1935 |
Ben Finney
--
https://mail.python.org/mailman/listinfo/python-list
