After having been called out on wrong default arg notation in one of my patches (eg. function:: copyfile(src, dst[, symlinks=False])), I've done a "grep -RPi "\[\w+=" Doc/library" and fixed the cases I've found – many of them sadly from myself (all the symlinks=False ones). ;)

The patch is against tip, I'd back port it to 3.2 if the contents is okay (and do it for 2.7 too, there's a lot of this errors there, I suppose docs fixes are okay for 2.7?).

The patch looks good to me, however in

-.. method:: epoll.poll([timeout=-1[, maxevents=-1]])
+.. method:: epoll.poll(timeout=-1, maxevents=-1)

it seems that maxevents can be passed only if timeout is specified, and this information is now lost in the signature.  If this is indeed true, it should be written down in the doc.

Looking at the code of epoll.poll(), it seems that 

   epoll.poll(timeout=-1, maxevents=-1)

is correct and the old 

   epoll.poll([timeout=-1[, maxevents=-1]])

is wrong, as there's no dependency between timeout and maxevents.

I had to expand the patch a bit by default args that weren't caught before. So here is still against default. It applies also against 3.2, only missing stuff fails AFAICT. (and yes, I checked the mknod device arg).

2.7 is in the works.

Here's against 2.7 which proved to be a can of worms. I tried to be as unobstructive as possible.

Please have a look at it, I'm sure I forgot some parenthesis somewhere.

I think there’s already one report for this.

Are you referring to #8350?

Yes.  Close as duplicate?

This issue is about documentation style of function signatures, not about missing keyword arguments in C functions.

Indeed.

Now we’re all on the same page – any opinions on the patches themselves? :)

The 3.x patch looks good to me.

What comes to the 2.7 patch, there's at least the problem with fmtparam in the csv module (should be **fmtparams instead of [, fmtparam]). And that's were I stopped reviewing, so there may also be other errors. Maybe the problem(s) should first be fixed on a case-by-case basis and then fix the style-only issues with one big patch.

New changeset d13fdd97cc8e by Hynek Schlawack in branch '3.2':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/d13fdd97cc8e

New changeset 2293eba03348 by Hynek Schlawack in branch 'default':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/2293eba03348

New changeset 8b7cb7e4ed8b by Hynek Schlawack in branch 'default':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/8b7cb7e4ed8b

I agree. I’ve committed the uncontroversial and mostly unrelated 3.x patch and will look at the special cases of 2.7 now.

New changeset a36666c52115 by Hynek Schlawack in branch '2.7':
#14804: Remove [] around optional arguments with default values
http://hg.python.org/cpython/rev/a36666c52115

The problematic cases have been outsourced to Issue14880 & Issue14870. Closing this one.