[Python-Dev] Best practice for documentation for std lib (original) (raw)

Alexander Belopolsky alexander.belopolsky at gmail.com
Tue Sep 24 03:59:55 CEST 2013

Given near-consensus on the "Return ..." form, the following discussion is of academic interest only.

On Mon, Sep 23, 2013 at 9:31 PM, Steven D'Aprano <steve at pearwood.info>wrote:

> I would not mind > > def foo(): > """returns bar""" > > which I would read as "Function foo() returns bar," but in this case > "returns" should be in lower case.

I certainly don't like that. Sentences, even eroded sentences, start with capital letters in English. Unless you are the poet e.e. cummings, capital letters are non-negotiable.

I still believe "Returns bar." is a non-sentence even if "Return bar!" is. While absence of subject noun in itself may not be an issue, but combined with a singular third-person verb form, it makes "Returns bar." grammatically incorrect. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20130923/5de51848/attachment.html>

More information about the Python-Dev mailing list