(original) (raw)
Yes on one line, capitalized, period. No on single sentence.
--Guido van Rossum (sent from Android phone)
On 06/26/2013 08:56 PM, Guido van Rossum wrote:
PEP 257 says this on the formatting of multi-line docstrings:"""
Multi-line docstrings consist of a summary line just like a one-line
docstring, followed by a blank line, followed by a more elaborate
description. The summary line may be used by automatic indexing tools;
it is important that it fits on one line and is separated from the
rest of the docstring by a blank line. [...]
"""I still like this rule, but it is violated frequently, in the stdlib
and elsewhere. I'd like to urge stdlib contributors and core devs to
heed it -- or explain why you can't.
Argument Clinic could conceivably enforce this.� It could mandate
that the first paragraph of the function docstring contain exactly
one sentence (must end in a period, all embedded periods cannot be
followed by
whitespace).� This would make some things nicer; I could
automatically insert the per-parameter docstrings in after the
summary.
Should it?
/arry
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe: http://mail.python.org/mailman/options/python-dev/guido%40python.org