[Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)
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?
> Python-Dev mailing list
> Python-Dev at python.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-Dev