Fix/update missing parameters in function signatures for Built-in Functions documentation

@rhettinger

BPO	46092
Nosy	@rhettinger, @AlexWaygood, @vivekvashist
PRs	gh-90250: Fix/update missing parameters in function signatures for Built-in Functions documentation #30128

^{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']

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.

PR: #30128

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.

Noticed that new removeprefix() and removesuffix() functions that were added in 3.9 have slash notation added in Built-in Types document[ation]

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.

I don't think changes like this (from #30128) are much of an improvement:

-.. function:: abs(x)
+.. function:: abs(x, /)

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.

Please could you open a discussion, or issue at https://github.com/python/editorial-board/?

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 help and 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, or The 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.

I think Alex made a good point in #90250 (comment):

If the view is that the slash notation should not be added to this piece of documentation, since it is aimed at beginners, should help() be changed so that it does not include the slash notation for built-in functions?

We should consider the implications (for beginners) of leaving help(func) and the docs for func inconsistent with each other.

Yes, but I think that discussion should be on Discuss 🙂

Yes, but I think that discussion should be on Discuss 🙂

I agree :)

Sounds to me we can close this as not-planned, and continue the discussion in a broader forum :)

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.

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.

Completed in 65fb4d1.

Navigation Menu

Repository navigation

Fix/update missing parameters in function signatures for Built-in Functions documentation #90250

3 remaining items

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Fix/update missing parameters in function signatures for Built-in Functions documentation #90250

Description

Activity

vivekvashist commented on Dec 15, 2021

vivekvashist commented on Dec 15, 2021

rhettinger commented on Dec 16, 2021

3 remaining items

merwok commented on Feb 10, 2024

hugovk commented on Feb 10, 2024

CAM-Gerlach commented on Feb 10, 2024

erlend-aasland commented on Feb 12, 2024

merwok commented on Feb 12, 2024

erlend-aasland commented on Feb 12, 2024

erlend-aasland commented on Feb 12, 2024

merwok commented on Feb 12, 2024

erlend-aasland commented on Feb 13, 2024

StanFromIreland commented on Aug 20, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions