Switch datetime docstrings / documentation to using "Returns" rather than "Return"?

[pganssle]

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

[pganssle]

In bpo-9305, Fred Drake recommends preferring Returns ... over the imperative Return ...: https://bugs.python.org/issue9305#msg110912

Currently 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]

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]

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]

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)