➜

This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Switch datetime docstrings / documentation to using "Returns" rather than "Return"?
Type: Stage:
Components: Documentation Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: belopolsky, docs@python, fdrake, p-ganssle, slateny
Priority: normal Keywords:

Created on 2022-04-03 16:08 by p-ganssle, last changed 2022-04-11 14:59 by admin.

Messages (2)
msg416628 - (view) Author: Paul Ganssle (p-ganssle) * (Python committer) Date: 2022-04-03 16:08 
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 https://github.com/python/cpython/pull/31697.
msg416760 - (view) Author: Stanley (slateny) * Date: 2022-04-05 07:58 
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.
History
Date User Action Args
2022-04-11 14:59:58adminsetgithub: 91363
2022-04-05 07:58:04slatenysetmessages: + msg416760
2022-04-03 16:08:25p-gansslecreate