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

[Antoine Pitrou]

Le Wed, 26 Jun 2013 18:56:10 -0700,
Guido van Rossum <guido at python.org> a écrit :
> 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.

I don't always find it easy to summarize a function in one line.

Regards

Antoine.