Repository navigation
Fix/update missing parameters in function signatures for Built-in Functions documentation #90250
Closed as duplicate
Description
| BPO | 46092 |
|---|---|
| Nosy | @rhettinger, @AlexWaygood, @vivekvashist |
| PRs |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2021-12-15.23:27:12.276>
labels = ['3.11', 'type-bug', '3.9', '3.10', 'docs']
title = 'Fix/update missing parameters in function signatures for Built-in Functions documentation.'
updated_at = <Date 2021-12-17.21:20:50.675>
user = 'https://github.com/vivekvashist'bugs.python.org fields:
activity = <Date 2021-12-17.21:20:50.675>
actor = 'vivekvashist'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2021-12-15.23:27:12.276>
creator = 'vivekvashist'
dependencies = []
files = []
hgrepos = []
issue_num = 46092
keywords = ['patch']
message_count = 5.0
messages = ['408653', '408655', '408676', '408678', '408817']
nosy_count = 4.0
nosy_names = ['rhettinger', 'docs@python', 'AlexWaygood', 'vivekvashist']
pr_nums = ['30128']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue46092'
versions = ['Python 3.9', 'Python 3.10', 'Python 3.11']
Activity
vivekvashist commentedon Dec 15, 2021
Previous issue:
#30113 (comment)
As noted/pointed by Alex - I went through all the Built-in Functions and updated/fixed the missing parameters.
I'll raise a PR shortly.
vivekvashist commentedon Dec 15, 2021
PR: #30128
rhettinger commentedon Dec 16, 2021
My understanding is that we're holding off on adding the slash notation to the main docs. The reason is that they are mostly unintelligible to the average user.
3 remaining items
merwok commentedon Feb 10, 2024
This could be removed then 🙂 It does not necessarily mean that all other instances can use slash.
I think there should be a broader agreement (than just a PR and reviews) on this doc convention, with a Discuss thread or by asking the docs editorial board.
hugovk commentedon Feb 10, 2024
I don't think changes like this (from #30128) are much of an improvement:
Please could you open a discussion, or issue at https://github.com/python/editorial-board/?
[-]Fix/update missing parameters in function signatures for Built-in Functions documentation.[/-][+]Fix/update missing parameters in function signatures for Built-in Functions documentation[/+]CAM-Gerlach commentedon Feb 10, 2024
Absent a well-motivated reason for the particular difference, there seems to be at least some value in making the docs and the docstrings consistent here on param naming, at least for the frequently-used builtin functions documented here. These builtins are the functions first and likely some of the most frequently used by new beginners, who are most likely to be unnecessarily confused why the parameter names shown by
helpand the docs differ.As for
/, I believe this has been discussed before on Discourse in this context (though couldn't find the thread), with mixed opinions; it aids consistently, correctness and explicitness as expected in a reference doc like this, but there was also significant concern it could be a point of confusion for beginners. My suggestion there was to automatically make/(and*) either an:abbr:with a short popup explaining its meaning (e.g.Parameters to the left of / are positional-only, orThe parameters to the left can only be passed by position, not keyword); or a cross-reference link to the appropriate glossary entry or explanation.In any case, IMO a further discussion on Discourse would be best as the first port of call, and if there isn't consensus, asking the EB to consider the matter.
erlend-aasland commentedon Feb 12, 2024
I think Alex made a good point in #90250 (comment):
We should consider the implications (for beginners) of leaving
help(func)and the docs forfuncinconsistent with each other.merwok commentedon Feb 12, 2024
Yes, but I think that discussion should be on Discuss 🙂
erlend-aasland commentedon Feb 12, 2024
I agree :)
erlend-aasland commentedon Feb 12, 2024
Sounds to me we can close this as not-planned, and continue the discussion in a broader forum :)
merwok commentedon Feb 12, 2024
IMO closing as not-planned would be the outcome of a discussion, not an indicator that a discussion is happening at the moment.
OTOH it’s easy to close and to reopen later.
erlend-aasland commentedon Feb 13, 2024
I closed the PR. It does not make sense to continue working on it until there is a general agreement. I'm fine with keeping this open.
StanFromIreland commentedon Aug 20, 2026
Completed in 65fb4d1.