classification
Title: Builtins in doc show signature in documentation
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.9
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: cryvate, docs@python, eric.smith, terry.reedy
Priority: normal Keywords:

Created on 2020-05-16 15:26 by cryvate, last changed 2020-05-23 07:18 by terry.reedy. This issue is now closed.

Messages (4)
msg369053 - (view) Author: Henk-Jaap Wagenaar (cryvate) * Date: 2020-05-16 15:26
Due to a certain discussion on extending zip, I was having looking at this page:

https://docs.python.org/3/library/functions.html

It lists the builtins at the top as e.g. all() which I think is confusing: running all() will actually fail.

I think it should either (using "all" as example):
1. display as "all"
2. display as "all(iterable)" (what to do about 'overloaded' functions like e.g. range?)

I am happy to provide a PR for the preferred option.
msg369058 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-05-16 16:03
It's a common convention to show a function with parens, even if it can't be called with no arguments. I don't think we want to make that table visually more complex by including all of the message signatures. open() has 8 params, min() and max() have multiple signatures, etc.

You could argue that removing the parens would be an improvement, since all items in the table are functions, but I think it's fine as it is.
msg369207 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2020-05-18 12:42
"message signatures" ->  "function signatures"
msg369695 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-05-23 07:18
I would probably prefer the table without the '()'s.  (I would have to see to be sure.)  However, the entries in the source .rst are all tagged with ':func:', as in ":func:`abs`", and that tag both adds "()" and makes the entries click-linked to the entries (which are tagged "function:: abs(x)", etc).  This is the standard used in the doc and whatever I might prefer, I will not propose adding a variant tag just for the table.
History
Date User Action Args
2020-05-23 07:18:33terry.reedysetstatus: open -> closed

nosy: + terry.reedy
messages: + msg369695

resolution: rejected
stage: resolved
2020-05-18 16:41:08rahul-kumisetnosy: - rahul-kumi
2020-05-18 16:41:01rahul-kumisetnosy: + rahul-kumi
2020-05-18 12:42:06eric.smithsetmessages: + msg369207
2020-05-16 16:03:43eric.smithsetnosy: + eric.smith
messages: + msg369058
2020-05-16 15:26:40cryvatecreate