This issue is part of the Great Argument Clinic Conversion Derby,
where we're trying to convert as much of Python 3.4 to use
Argument Clinic as we can before Release Candidate 1 on January 19.

This issue asks you to change the following bundle of files:
    Modules/socketmodule.c: 47 sites
    Modules/socketmodule.h: 1 sites
    Modules/_functoolsmodule.c: 2 sites

Talk to me (larry) if you only want to attack part of a bundle.

For instructions on how to convert a function to work with Argument
Clinic, read the "howto":
    http://docs.python.org/dev/howto/clinic.html

Taking a crack at this.

socketmodule.h: just a comment, skipping.

_functools.c: kind-of skipping, because the relevant functions are not normally directly called (pickle protocol __reduce__ and __setstate__ on partial, __call__ on cmp wrapper). Will add simple docstrings for the pickle protocol handlers though.

While it's dandy to add docstrings, your patch doesn't have any Argument Clinic stuff in it.  I don't mind if you add docstrings as part of the process of converting to Argument Clinic, but I'm not interested in this patch as it stands.

Just discovered that the bugtracker mail was all going into my spam filter, yay. Didn't notice your reply until just now.

The functools patch was just a quickie to get it out of my mental queue, and I'm still working on socketmodule. This is my first time using the Python bugtracker, I don't know if multipart patches are acceptable?

I don't know what you mean by a "multipart patch", but the bug tracker has handled every patch I've thrown at it so far.  (Assuming that the patch is based on a reasonably fresh checkout of trunk.)

Here's the socketmodule patch. I aggressively imported text from the docs for the docstrings, along with matching parameter names, given how far the old docstrings have drifted over time. The Windows-specific code is untested, but otherwise the tests pass. I tagged functions which can't be converted or whose argument handling is esoteric. These comments can be removed prior to commit.

I am not sure if one should convert a C-level class's init method.

Forgot to linewrap a paragraph.

Tweaked the argument list for functions using a NULL default. Kludgy but doesn't lie to the user.

Here's sendmsg with only nested bracket optional args. If Rietveld doesn't like this patch I may cry.

Ryan, 4 hunks of your patch fail to apply now. Can you please update the patch?

All the Derby patches should only go into trunk at this point.

I am working on revising the Argument Clinic definitions for socketmodule.c.