[Doc-SIG] Proposal: don't nest optional brackets

[Cristina Yenyxe González García]

2008/9/24 A.M. Kuchling <amk at amk.ca>:
> On Tue, Sep 16, 2008 at 07:10:59PM -0400, Fred Drake wrote:
>
> I think nesting the optional arguments doesn't actually indicate
> whether keywords are supported or not.  For example,
> two functions from the socket module are:
>
> .. function:: getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
> .. method:: socket.recv_into(buffer[, nbytes[, flags]])
>
> getaddrinfo() doesn't support keyword arguments; recv_into() does.
> But nesting the brackets does add a lot of typographical fluff.
>
> Can we invent a new notation for separating which functions support
> keywords and which don't?  How would we render that distinction
> typographically in the output?
>

I would like to suggest an idea which wouldn't involve typographical
changes. I think keyword arguments could be represented just if they
were in a dictionary, something like: buffer, **{nbytes, flags}
Maybe it would take some time for the people to get used to the new
syntax, but I think is it, at least, similar to Python code.