I wish to add documentation for the constants in the socket module. AF_*, SO_*, MSG_* etc. Some of them are really useful such as SO_KEEPALIVE and MSG_WAITALL. The modules documentation currently just refers the reader to UNIX manual pages, but I think we can do better.

This patch is for the AF_* constants. If it is accepted, I'd like to submit patches for the other constants too. Maybe there should be a subsection for all constants?

I fear that intermixing \dataline with content within one datadesc is not correct.

I think I'd put the constants and their explanation into a table.

I assume you like the general idea of the patch then? I'll create a patch with the tables and create a new subsection to contain them.

Yes, more documentation is almost always better than less. :-)

Be sure to use reST format now that we've switched to that. Much easier
to type :)

Is there progress on this?

Yes, having a subsection describing such things would be a cool idea.
Please don't leave behind this ticket.

There is no progress on this. I had lots of documentation written in
Latex on a laptop, but then I lost it. Sorry.

msg67121 states proposed changes were lost :(

Resolution "won't fix" is inappropriate.  We'd love to fix it, but someone has to volunteer to (re)write the doc update...

Reopening because the consensus seems to be to update and apply this sort of change.

Issue 12887 is open to add explanations of the SO_* constants

Gonna take this and its dependencies on, eta 2-4 days.

I've opened up a PR for this ticket's dependencies. There's some things I'm looking for feedback on there: https://github.com/python/cpython/pull/3072

Issue 13256 contains a patch documenting socket options, but was closed because the author lost interest.

Issue 27409 is a proposal to list the symbols available without documenting what each one is for.

The general rule for documenting availability seems to be to only list the special cases. Many of the socket options are specified by Posix, and seem to be available on Linux, Windows, BSD and other OSes. If you say “Availability: Linux, Windows”, it could imply that the API is specific to those two platforms, and not available on Free BSD or other platforms in general.

That makes sense, listing availability for exceptions would certainly make everything more succinct. How do you propose we mention that certain options don't actually do anything on Windows. Currently I have a footnote in the table that links to the MSDN documentation here: https://msdn.microsoft.com/en-us/library/windows/desktop/ms740532(v=vs.85).aspx



control+f for "SO_RCVLOWAT" for example