Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Open
pganssle opened this issue Apr 3, 2022 · 2 comments
Open

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

pganssle opened this issue Apr 3, 2022 · 2 comments
Labels
3.11 docs Documentation in the Doc dir

Comments

@pganssle
Copy link
Member

pganssle commented Apr 3, 2022

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
Copy link
Member Author

pganssle commented Apr 3, 2022

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.

@pganssle pganssle added the 3.11 label Apr 3, 2022
@pganssle pganssle added docs Documentation in the Doc dir 3.11 labels Apr 3, 2022
@pganssle pganssle added the docs Documentation in the Doc dir label Apr 3, 2022
@slateny
Copy link
Contributor

slateny commented 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.

@ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
3.11 docs Documentation in the Doc dir
Projects
Date and time issues
Status: No status
Milestone
No milestone
Development

No branches or pull requests
2 participants
@pganssle @slateny