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

➜

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.

This issue has been migrated to GitHub: https://github.com/python/cpython/issues/91363

classification

标题:	Switch datetime docstrings / documentation to using "Returns" rather than "Return"?
类型:		Stage:
Components:	Documentation	Versions:	Python 3.11

process

状态:	open	Resolution:
Dependencies:		后续:
分配给:	docs@python	抄送列表:	belopolsky, docs@python, fdrake, p-ganssle, slateny
优先级:	normal	关键字:

p-ganssle 于 2022-04-03 16:08 创建。最近一次由 admin 于 2022-04-11 14:59 修改。

Messages (2)
msg416628 - (view)	Author: Paul Ganssle (p-ganssle) *	日期: 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) *	日期: 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.