[Python-Dev] Best practice for documentation for std lib

[Alexander Belopolsky]

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>