Repository navigation
Switch datetime docstrings / documentation to using "Returns" rather than "Return"? #91363
Closed as not planned
Description
| BPO | 47207 |
|---|---|
| Nosy | @freddrake, @abalkin, @pganssle, @slateny |
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 2022-04-03.16:08:25.072>
labels = ['3.11', 'docs']
title = 'Switch datetime docstrings / documentation to using "Returns" rather than "Return"?'
updated_at = <Date 2022-04-05.07:58:04.312>
user = 'https://github.com/pganssle'bugs.python.org fields:
activity = <Date 2022-04-05.07:58:04.312>
actor = 'slateny'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2022-04-03.16:08:25.072>
creator = 'p-ganssle'
dependencies = []
files = []
hgrepos = []
issue_num = 47207
keywords = []
message_count = 2.0
messages = ['416628', '416760']
nosy_count = 5.0
nosy_names = ['fdrake', 'belopolsky', 'docs@python', 'p-ganssle', 'slateny']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue47207'
versions = ['Python 3.11']
Activity
pganssle commentedon Apr 3, 2022
In bpo-9305, Fred Drake recommends preferring
Returns ...over the imperativeReturn ...: https://bugs.python.org/issue9305#msg110912Currently we're pretty consistent about
Return ..., which is consistent with PEP-257: https://peps.python.org/pep-0257/That said, I actually think "Returns ..." sounds much better in the documentation, and I'd be happy to see it changed if others agree.
I have spun this off from bpo-9305 so that we can unblock #31697.
slateny commentedon Apr 5, 2022
Is there a bpo page or some sort that discusses why the imperative mood is used over the indicative mood other than convention of PEP-257? I found this (https://mail.python.org/pipermail/tutor/2012-May/089584.html) question and answer that seems to make sense, but it's not quite an official source.
If the reason for using imperative mood in docstrings doesn't apply to documentation, then I think there wouldn't be any problems in changing it. One thing raised in the mail thread was that 'Returns ...' isn't strictly grammatical, so perhaps that's something to consider.
StanFromIreland commentedon Mar 8, 2025
This would break PEP 257 however the Google Python style guide allows both imperative and descriptive docstrings.
This discussion should be moved elsewhere as this is relevant to more than just datetime.
Edit: Created discuss topic.
picnixz commentedon Mar 8, 2025
My 2c: I prefer "Return" over "Returns" because it saves 1 char (so that we can sometimes fit stuff on 80 chars). Im addition, IIRC, most of the rest of the C comments use imperative mood but maybe I'm mistaken (I think the rest of the C API docs use "Return 0 on success and -1 with an exception set on failure" most of the time but correct me if I'm wrong).
If we want to pursue this issue, this should probably be something decided by the editorial board though (it doesn't affect the rendered docs directly so that's why I haven't tagged them yet)
AA-Turner commentedon Mar 8, 2025
I also prefer the imperative mood, and suggest closing this issue if there is not significant support for change on the Discourse thread.
Note docstrings are explicitly out of scope for the EB, so this would just be a normal decision by consensus (or escalation to the steering council if core developers cannot find consensus).
A
picnixz commentedon Mar 8, 2025
Oh I didn't remember that docstrings were excluded. Good that I didn't tag them :')
StanFromIreland commentedon Mar 9, 2025
@picnixz This can be closed
hugovk commentedon Mar 9, 2025
Closing following discussion.
https://discuss.python.org/t/pep-257-allow-docstrings-to-be-descriptive-indicative-style/83652/
terryjreedy commentedon Mar 9, 2025
I also prefer 'Return ...'.