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

[Guido van Rossum]

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.

-- 
--Guido van Rossum (python.org/~guido)