Message 110916 - Python tracker

➜

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.

Author	techtonik
Recipients	belopolsky, docs@python, fdrake, techtonik, tim.peters
Date	2010-07-20.16:08:05
SpamBayes Score	0.014330682
Marked as misclassified	No
Message-id	<AANLkTil6qv86_4d49phmw_t9XXev9Wgk2_5OvQwFe4fT@mail.gmail.com>
In-reply-to	<AANLkTinGi_JMj6gbT0Pp9uMz_K9FuTfuinM1tiVU37Ct@mail.gmail.com>

Content
> Documenting utcoffset() as "Return timedelta equal to local UTC > offset." is almost circular. It does not explain whether it has to be > added or subtracted from UTC to arrive at local time. Ok. Sold. >> I believe the correct convention is "Return timedelta...". > > This is handled inconsistently in the documentation; I'm hoping the > current maintainers reinforce the "Returns ..." structure. The > documentation is descriptive, not an external specification. http://www.python.org/dev/peps/pep-0257/#one-line-docstrings I've took the convention from here. I thought docs are generated from docstrings.

> Documenting utcoffset() as "Return timedelta equal to local UTC
> offset." is almost circular.  It does not explain whether it has to be
> added or subtracted from UTC to arrive at local time.

Ok. Sold.

>> I believe the correct convention is "Return timedelta...".
>
> This is handled inconsistently in the documentation; I'm hoping the
> current maintainers reinforce the "Returns ..." structure.  The
> documentation is descriptive, not an external specification.

http://www.python.org/dev/peps/pep-0257/#one-line-docstrings

I've took the convention from here. I thought docs are generated from
docstrings.

History
Date	User	Action	Args
2010-07-20 16:08:08	techtonik	set	recipients: + techtonik, tim.peters, fdrake, belopolsky, docs@python
2010-07-20 16:08:06	techtonik	link	issue9305 messages
2010-07-20 16:08:05	techtonik	create