<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy <span dir="ltr"><<a href="mailto:tjreedy@udel.edu" target="_blank">tjreedy@udel.edu</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On 9/22/2013 10:04 PM, Guido van Rossum wrote:<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
If I had the final word, I'd recommend using the current docstrings as<br>
the .rst contents and replacing the docstrings with the 1-2 line<br>
function descriptions from the PEP, e.g.:<br>
<br>
             * median(data) -> median (middle value) of data, taking the<br>
               average of the two middle values when there are an even<br>
               number of values.<br>
<br>
But omitting the signature proper, and replacing "->" with "Returns" or<br>
"Returns the". E.g.<br>
<br>
     def median(data):<br>
         """Returns the median (middle value) of data, taking the<br>
            average of the two middle values when there are an even<br>
            number of values.<br>
         """<br>
         ...<br>
<br>
I'd personally also rewrite them all so that the first line of the<br>
docstring is a phrase that can stand by itself, as I describe in PEP 8,<br>
but this is used only sporadically in the stdlib.<br>
</blockquote>
<br></div>
I am gradually changing Idle docstrings, though only Idle developers will ever see them. Writing a 60 char summary forces a clear understanding of the function. Applied to the above.<br>
<br>
      def median(data):<br>
          """Return the median (middle value) of data.<br>
<br>
          Use the average of the two middle values when<div class="im"><br>
          there are an even number of values.<br>
          """<br></div></blockquote><div><br></div><div>Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(<br> <br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">

<div class="im"></div>
('Return' rather than 'Returns' is the current convention.)<span class="HOEnZb"><font color="#888888"></font></span><br></blockquote></div><br></div><div class="gmail_extra">That's actually a religious argument which in the stdlib takes no strict position -- a quick grep shows that both  are used, although 'Return' is more frequent by a 5-to-1 margin. IIRC in the Java world you *have* to use 'Returns', but I don't buy the argument from nit-picky grammarians that leads to this rule. (It's something about the documentation not being a command. But English is more flexible than that.)<br clear="all">

</div><div class="gmail_extra"><br>-- <br>--Guido van Rossum (<a href="http://python.org/~guido">python.org/~guido</a>)
</div></div>