Document the constants in the socket module

[sonderblade]

BPO	1732367
Nosy	@birkenfeld, @giampaolo, @bitdancer, @vadmium, @ammaraskar
Dependencies	bpo-12887: Documenting all SO_* constants in socket module bpo-13256: Document and test new socket options bpo-14345: Document socket.SOL_SOCKET bpo-27409: List socket.SO_, SCM_, MSG_, IPPROTO_ symbols
Files	doc-for-socket-af-constants.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2007-06-06.20:46:18.000>
labels = ['type-feature', '3.7', 'docs']
title = 'Document the constants in the socket module'
updated_at = <Date 2017-08-12.12:12:03.630>
user = 'https://bugs.python.org/sonderblade'

bugs.python.org fields:

activity = <Date 2017-08-12.12:12:03.630>
actor = 'ammar2'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2007-06-06.20:46:18.000>
creator = 'sonderblade'
dependencies = ['12887', '13256', '14345', '27409']
files = ['8037']
hgrepos = []
issue_num = 1732367
keywords = ['patch']
message_count = 17.0
messages = ['52732', '52733', '52734', '52735', '59375', '66743', '66751', '67121', '116686', '116690', '269459', '272496', '299206', '300151', '300189', '300192', '300197']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'sonderblade', 'giampaolo.rodola', 'bjourne', 'r.david.murray', 'martin.panter', 'ammar2']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1732367'
versions = ['Python 3.7']

Linked PRs

• gh-45048: Document the availability and uses of the SO_ constants #132752

[sonderblade]

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?

[birkenfeld]

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.

[sonderblade]

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.

[birkenfeld]

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

[birkenfeld]

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

[birkenfeld]

Is there progress on this?

[giampaolo]

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

[bjourne]

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

[BreamoreBoy]

msg67121 states proposed changes were lost :(