<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<div class="moz-cite-prefix">On 06/26/2013 08:56 PM, Guido van
Rossum wrote:<br>
</div>
<blockquote
cite="mid:CAP7+vJKyONB1GK9tN=SuLiH=C9Uf7HQR1zm2m+5VMYY4pPN_Yw@mail.gmail.com"
type="cite">
<pre wrap="">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.
</pre>
</blockquote>
<br>
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<br>
whitespace). This would make some things nicer; I could
automatically insert the per-parameter docstrings in after the
summary.<br>
<br>
Should it?<br>
<br>
<br>
<i>/arry</i><br>
</body>
</html>