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

Issue47207

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) *	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.