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

Created on 2014-02-10 14:24 by roysmith, last changed 2019-01-21 04:51 by demian.brecht.

Messages (6)
msg210838 - (view) Author: Roy Smith (roysmith) Date: 2014-02-10 14:24

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.
Date User Action Args
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