Documenting a function signature (was: Set a flag on the function or a global?)

[Ben Finney]

Steven D'Aprano <steve at 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