New submission from Roy Smith:
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.
assignee: docs@python components: Documentation messages: 210838 nosy: docs@python, roysmith priority: normal severity: normal status: open title: socket.getnameinfo() does not document flags versions: Python 2.7
R. David Murray added the comment:
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.
nosy: +r.david.murray versions: +Python 3.3, Python 3.4
Roy Smith added the comment:
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.
Demian Brecht firstname.lastname@example.org added the comment:
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.
miss-islington email@example.com added the comment:
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/3993ccb6820d4239ce3d9e1c5d31f13b86e...