Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document the constants in the socket module #45048

Open
sonderblade mannequin opened this issue Jun 6, 2007 · 17 comments
Open

Document the constants in the socket module #45048

sonderblade mannequin opened this issue Jun 6, 2007 · 17 comments
Labels
docs Documentation in the Doc dir type-feature A feature request or enhancement

Comments

@sonderblade
Copy link
Mannequin

sonderblade mannequin commented Jun 6, 2007

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']
    @sonderblade
    Copy link
    Mannequin Author

    sonderblade mannequin commented Jun 6, 2007

    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?

    @sonderblade sonderblade mannequin added docs Documentation in the Doc dir labels Jun 6, 2007
    @birkenfeld
    Copy link
    Member

    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
    Copy link
    Mannequin Author

    sonderblade mannequin commented Jun 7, 2007

    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
    Copy link
    Member

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

    @birkenfeld
    Copy link
    Member

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

    @birkenfeld
    Copy link
    Member

    Is there progress on this?

    @giampaolo
    Copy link
    Contributor

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

    @bjourne
    Copy link
    Mannequin

    bjourne mannequin commented May 20, 2008

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

    @BreamoreBoy
    Copy link
    Mannequin

    BreamoreBoy mannequin commented Sep 17, 2010

    msg67121 states proposed changes were lost :(

    @BreamoreBoy BreamoreBoy mannequin closed this as completed Sep 17, 2010
    @BreamoreBoy BreamoreBoy mannequin closed this as completed Sep 17, 2010
    @bitdancer
    Copy link
    Member

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

    @bitdancer bitdancer added type-feature A feature request or enhancement labels Sep 17, 2010
    @vadmium
    Copy link
    Member

    vadmium commented Jun 29, 2016

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

    @vadmium vadmium reopened this Jun 29, 2016
    @vadmium vadmium reopened this Jun 29, 2016
    @vadmium
    Copy link
    Member

    vadmium commented Aug 12, 2016

    bpo-12887 is open to add explanations of the SO_* constants

    @ned-deily ned-deily added the 3.7 (EOL) end of life label Jul 26, 2017
    @ned-deily ned-deily added the 3.7 (EOL) end of life label Jul 26, 2017
    @ammaraskar
    Copy link
    Member

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

    @ammaraskar
    Copy link
    Member

    I've opened up a PR for this ticket's dependencies. There's some things I'm looking for feedback on there: #3072

    @vadmium
    Copy link
    Member

    vadmium commented Aug 12, 2017

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

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

    @vadmium
    Copy link
    Member

    vadmium commented Aug 12, 2017

    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.

    @ammaraskar
    Copy link
    Member

    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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @AlexWaygood AlexWaygood removed the 3.7 (EOL) end of life label May 11, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    docs Documentation in the Doc dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    7 participants
    @birkenfeld @bitdancer @giampaolo @ammaraskar @vadmium @ned-deily @AlexWaygood