[Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257) (original) (raw)

Guido van Rossum guido at python.org
Thu Jun 27 17:57:32 CEST 2013

Yes on one line, capitalized, period. No on single sentence.

--Guido van Rossum (sent from Android phone) On Jun 27, 2013 8:17 AM, "Larry Hastings" <larry at hastings.org> wrote:

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 at python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/guido%40python.org -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20130627/65ec1b82/attachment.html>

More information about the Python-Dev mailing list