[issue40646] Builtins in doc show signature in documentation

New submission from Henk-Jaap Wagenaar <wagenaarhenkjaap@gmail.com>: 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. ---------- assignee: docs@python components: Documentation messages: 369053 nosy: cryvate, docs@python priority: normal severity: normal status: open title: Builtins in doc show signature in documentation type: enhancement versions: Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40646> _______________________________________

Eric V. Smith <eric@trueblade.com> added the comment: 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. ---------- nosy: +eric.smith _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40646> _______________________________________

Eric V. Smith <eric@trueblade.com> added the comment: "message signatures" -> "function signatures" ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40646> _______________________________________

Change by Rahul Kumaresan <kayrahul@gmail.com>: ---------- nosy: +rahul-kumi _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40646> _______________________________________

Change by Rahul Kumaresan <kayrahul@gmail.com>: ---------- nosy: -rahul-kumi _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40646> _______________________________________

Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +terry.reedy resolution: -> rejected stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue40646> _______________________________________
participants (4)
-
Eric V. Smith
-
Henk-Jaap Wagenaar
-
Rahul Kumaresan
-
Terry J. Reedy