classification
Title: socket.getnameinfo() does not document flags
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: danishprakash, demian.brecht, docs@python, miss-islington, r.david.murray, roysmith, serhiy.storchaka
Priority: normal Keywords: easy, patch

Created on 2014-02-10 14:24 by roysmith, last changed 2019-04-11 21:13 by miss-islington.

Pull Requests
URL Status Linked Edit
PR 11977 merged eamanu, 2019-02-21 13:56
Messages (8)
msg210838 - (view) Author: Roy Smith (roysmith) Date: 2014-02-10 14:24
http://docs.python.org/2/library/socket.html

The description for getnameinfo() says, "... Depending on the settings of flags, the result can contain a fully-qualified domain name or numeric address representation in host.", but does not say what to pass for flags to get those behaviors.
msg210839 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-10 14:32
Like the other socket functions, you have to look it up in the man page.  A number of the other functions that take a flag argument mention this in their description, so a similar mention should be added to the getnameinfo entry.
msg210841 - (view) Author: Roy Smith (roysmith) Date: 2014-02-10 14:38
What might make sense is for all of those, document the function call as taking "native_flags" (or something like that), with a single note at the top of the page saying, "native_flags means look up the specific values in the man page" and link to that note each time it's used.
msg210843 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-10 15:32
I thought about that, but different functions refer to different man pages, and it isn't always obvious from the function name which one.
msg330294 - (view) Author: Danish Prakash (danishprakash) * Date: 2018-11-23 02:59
I would like to work on this if nobody else has.
msg334110 - (view) Author: Demian Brecht (demian.brecht) * (Python triager) Date: 2019-01-21 04:51
What if the docs for socket functions that took system-level flag parameters had links to relevant online man pages? I don't think a single entry at the top of the page would be optimal. I know that I tend to skip the preamble and just go directly to the function I'm interested in.

I know that it's not a perfect solution because there's a good chance of those links going stale. I'm also relatively sure that we wouldn't want to have an exhaustive list. However, I think in this instance that /something/ would be better than nothing. Even if the link is stale or the target OS isn't included, it would give the reader a place to start, which is currently lacking.
msg336282 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2019-02-22 06:28
You can use the special role :manpage: for referring man pages.
msg339996 - (view) Author: miss-islington (miss-islington) Date: 2019-04-11 21:13
New changeset 3993ccb6820d4239ce3d9e1c5d31f13b86e0000b by Miss Islington (bot) (Emmanuel Arias) in branch 'master':
bpo-20582: add link for manpage for flags on getnameinfo() (GH-11977)
https://github.com/python/cpython/commit/3993ccb6820d4239ce3d9e1c5d31f13b86e0000b
History
Date User Action Args
2019-04-11 21:13:40miss-islingtonsetnosy: + miss-islington
messages: + msg339996
2019-02-22 06:28:58serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg336282
2019-02-21 13:56:39eamanusetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request12001
2019-01-21 04:51:43demian.brechtsetmessages: + msg334110
2019-01-21 04:32:30demian.brechtsetnosy: + demian.brecht
2018-11-23 02:59:07danishprakashsetnosy: + danishprakash
messages: + msg330294
2018-10-17 22:27:26cheryl.sabellasetkeywords: + easy
stage: needs patch
type: enhancement
versions: + Python 3.8, - Python 2.7, Python 3.3, Python 3.4
2014-02-10 15:32:35r.david.murraysetmessages: + msg210843
2014-02-10 14:38:48roysmithsetmessages: + msg210841
2014-02-10 14:32:31r.david.murraysetnosy: + r.david.murray

messages: + msg210839
versions: + Python 3.3, Python 3.4
2014-02-10 14:24:25roysmithcreate